In Sphinx, how can I create a linkable “terminology” section without massive overhead?

Question

I want to create a "terminology" section with definitions for terms that I'm using such that every time I use the terms in this terminology section, a link is created that points to the definition.

Currently, the best I can think up is:

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

.. _flavor:

flavor
------
blah blah blah

Then later, in the other text I have to do:

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

I find the above syntax to be very cumbersome. I know I could use yet another layer of scripting or m4 to auto-generate this syntax, but I'm hoping there's a better way..

Answer 1

Not so different, but you can use:

.. glossary::

This directive must contain a reST definition list with terms and definitions. The definitions will then be referencable with the 'term' role.

:term:

Reference to a term in the glossary. The glossary is created using the glossary directive containing a definition list with terms and definitions. It does not have to be in the same file as the term markup, for example the Python docs have one global glossary in the glossary.rst file.

If you use a term that’s not explained in a glossary, you’ll get a warning during build.

[pasted from official sphinx documentation]