Jak utworzyć globalną rolę/role w Sphinx?

Question

Jest to kontynuacja "ReST Strikethrough" ReST strikethrough, ale w kontekście Sphinx zamiast ReST. Moje pytanie brzmi, czy w sfinksie jest centralne miejsce, w którym można umieścić dyrektywę "roli" lub czy ta dyrektywa rzeczywiście musi być powtarzana w każdym pierwszym pliku w sfinksowaniu.

Bardziej szczegółowo:

Łatwo jest określić niestandardowe style CSS dla tekstu inline (patrz reszta Przekreślenie jako przykład) za pomocą dyrektywy Rola:

.. role:: custom 
    :class: custom 

This is an :custom:`inline text`. 

co przekłada się na renderowania html

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

także zwyczaj stylów może być łatwo dodana do sfinks (patrz http://www.tinkerer.me/doc/theming.html), w którym, aby dodać selektor klasy CSS kontrolować sposób niestandardowy „tekst” jest renderowany (kolor, przekreślony, czcionka, rozmiar ...)

Co przeszkadza mi w moich eksperymentach, musiałem powtórzyć dyrektywę roli w każdym pliku ReST, który używał niestandardowej roli. Czy istnieje "centralne" miejsce, w którym mogę zdefiniować to raz dla całej witryny?

Answer 1

Wygląda na to, że rst_prolog, które jest ustawione w pliku conf.py, jest centralnym miejscem, którego szukałem. Rst_prolog to "Ciąg tekstowy reStructuredText, który będzie zawarty na początku każdego przeczytanego pliku źródłowego". W moim przypadku, po prostu dodaje się następujące do conf.py:

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

Należy również zauważyć, że dla mojego celu rola dyrektywa bez attibute klasy działa dobrze.

Oczywiście, jak zauważył Chris, rst_prolog, który osiąga wiele rzeczy, można osiągnąć, włączając plik global.rst. [Możliwe jednak, że występują problemy z jego względną ścieżką. Może lepiej użyć rst_prolog = open ('global.rst', 'r'). Read() --untested]

Answer 2

Na przykład pod numerem documenting your project using sphinx można użyć include, aby zamienić plik global.rst zawierający wszystkie dyrektywy dotyczące ról na inne pliki. Z tej strony:

składni:

.. include:: myfile.rst 

Will "inline" dany plik (myfile.rst). Typową konwencją, której używam, jest utworzenie globalnego pliku .rst o nazwie global.rst i uwzględnienie go u góry każdej strony. Bardzo przydatne w przypadku odsyłaczy do popularnych obrazów lub zwykłych plików z linkami itp.