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

Question

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

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

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

.. 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
"""

Также обратите внимание, что для моей цели директива роли без класса 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 и включите это в верхней части каждой страницы. Очень полезно для ссылок на общие изображения или ссылки на общие файлы и т. Д.