Как мне создать глобальную роль / роли в Sphinx?

Question

Это продолжение "зачеркивания ReST" зачеркивание ReST , но в сфинксе, а не в контексте ReST. Мой вопрос заключается в том, есть ли в sphinx центральное место, куда следует помещать директиву «роль», или эта директива действительно должна повторяться в каждом первом файле в документации по сфинксу.

Более подробно:

Легко определить пользовательские стили CSS для встроенного текста (см. ReST Strikethrough в качестве примера), используя директиву роли:

.. role:: custom
   :class: custom

This is an :custom:`inline text`.

, что переводится в HTML-рендеринг

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

Кроме того, пользовательская таблица стилей может быть легко добавлена ​​в sphinx (см. http://www.tinkerer.me/doc/theming.html), где добавить селектор класса CSS для управления отображением «пользовательского» текста (цвет, зачеркивание, шрифт, размер ...)

Что меня беспокоит, так это то, что в моих экспериментах мне приходилось повторять директиву ролей в каждом файле ReST, в котором использовалась пользовательская роль. Есть ли «центральное» место, где я могу определить это один раз для всего сайта?

Answer 1

Кажется, что rst_prolog , который установлен в файле conf.py, является центральным местом, которое я искал.Rst_prolog - это «строка reStructuredText, которая будет включена в начало каждого исходного файла, который читается».В моем случае я просто добавил следующее к conf.py:

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

Обратите внимание, что для моей цели директива role без класса attibute работает просто отлично.

Очевидно, как указал Крис, rst_prolog, который выполняет множество задач, может быть достигнуто путем включения файла global.rst .[Однако могут быть проблемы с его относительным путем.Может быть, лучше использовать rst_prolog = open ('global.rst', 'r'). Read () --untested]

Answer 2

Из примера на , документирующего ваш проект с использованием sphinx , вы можете использовать include для замены файла global.rst, который содержит все ваши директивы роли, на другие ваши файлы , С этого сайта:

Синтаксис:

.. include:: myfile.rst

Будет "встроен" в данный файл (myfile.rst). Общее соглашение, которое я использую, - это создание глобального .rst файла с именем global.rst и включение его в начало каждой страницы. Очень полезно для ссылок на общие изображения или ссылки на общие файлы и т. Д.