В Sphinx, как я могу создать связанный раздел терминологии без больших накладных расходов?

Question

Я хочу создать раздел «терминологии» с определениями терминов, которые я использую, так что каждый раз, когда я использую термины в этом разделе терминологии, создается ссылка, указывающая на определение.

В настоящее время лучшее, что я могу придумать, это:

.. |flavor| replace:: `:ref:flavor`

.. _flavor:

flavor
------
blah blah blah

Потом позже, в другом тексте я должен сделать:

''' This is a usage of the word |flavor|.'''

Я считаю, что приведенный выше синтаксис очень громоздкий. Я знаю, что мог бы использовать еще один слой сценариев или m4 для автоматической генерации этого синтаксиса, но я надеюсь, что есть лучший способ ..

Answer 1

Не сильно отличается, но вы можете использовать:

.. глоссарий ::

Эта директива должна содержать список определений reST с терминами и определениями. Тогда определения будут ссылаться на роль «термин».

: Термин:

Ссылка на термин в глоссарии. Глоссарий создается с использованием директивы глоссария, содержащей список определений с терминами и определениями. Он не обязательно должен находиться в том же файле, что и разметка термина, например, документы Python имеют один глобальный глоссарий в файле glossary.rst.

Если вы используете термин, который не описан в глоссарии, вы получите предупреждение во время сборки.

[вставлено из официальной документации сфинкса]