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

Это продолжение "Замысла REST Strikethrough" 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, который использовал пользовательскую роль. Есть ли "центральное" место, где я могу определить это один раз для всего сайта?

Ответ 1

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

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

Заметьте также, что для моей цели директива роли без класса attitute работает отлично.

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

Ответ 2

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

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