Come posso creare un ruolo/ruoli globali in Sfinge?

Question

Questo è un seguito di "ReST Barrato" ReST strikethrough ma in una Sfinge piuttosto che in un contesto ReST. La mia domanda è se ci sia un posto centrale nella sfinge dove mettere una direttiva "ruolo" o se questa direttiva debba davvero essere ripetuta in ogni primo file all'interno di una documentazione della sfinge.

Più in dettaglio:

E 'facile da definire gli stili CSS personalizzati per il testo in linea (vedi ReST Barrato come esempio) utilizzando una direttiva ruolo:

.. role:: custom 
    :class: custom 

This is an :custom:`inline text`. 

che si traduce in un rendering HTML di

.. This is an <span class="custom">inline text</span>. .. 

Inoltre, è possibile aggiungere facilmente un foglio di stile personalizzato alla sfinge (vedere http://www.tinkerer.me/doc/theming.html) dove aggiungere un selettore di classe CSS per controllare il testo "personalizzato" è reso (colore, barrato, carattere, dimensione ...)

Ciò che mi disturba è che nei miei esperimenti, ho dovuto ripetere la direttiva del ruolo in ogni file di ReST che usava il ruolo personalizzato. Esiste un luogo "centrale" in cui posso definirlo una volta per l'intero sito?

Answer 1

Sembra che rst_prolog impostato nel file conf.py sia il punto centrale che stavo cercando. Rst_prolog è "Una stringa di ReStructuredText che sarà inclusa all'inizio di ogni file sorgente che viene letto". Nel mio caso, ho semplicemente aggiunto quanto segue conf.py:

rst_prolog = """ 
.. role:: test2 
""" 

Si noti inoltre che per il mio scopo, il ruolo direttivo senza attibute classe funziona bene.

Ovviamente, come Chris ha fatto notare, un rst_prolog che compie molte cose potrebbero essere raggiunti includendo un file di global.rst . [Potrebbero esserci problemi con il suo percorso relativo, comunque. Forse meglio usare rst_prolog = open ('global.rst', 'r'). Read() --untested]

Answer 2

Dall'esempio documenting your project using sphinx, è possibile utilizzare include per sostituire un file global.rst, che contiene tutte le direttive di ruolo, negli altri file. Da questo sito:

La sintassi:

.. include:: myfile.rst 

Will "in linea" il file data (myfile.rst). Una convenzione comune che utilizzo è creare un file .rst globale denominato global.rst e includerlo nella parte superiore di ogni pagina. Molto utile per collegamenti a immagini comuni o collegamenti a file comuni, ecc.