Glossary and abbreviations are generated by
sphinx_doc_glossary.py from the common source
doc/glossary.src
.
Either use dictionary/encyclopedia style[DICTTERM]
- term
- a word or group of words designating something, especially in a particular field, as atom in physics, quietism in theology, adze in carpentry, or district leader in politics.
or section style (term assumes the role of a section title)
Words, compound words or multi-word expressions[WPTERM]
[…] that in specific contexts are given specific meanings - these may deviate from the meanings the same words have in other contexts and in everyday language.
Do not mix styles.
Do not write a glossary entry as a single sentence:
Have a look at the google search glossary entries example.
It is possible to have multiple glossaries spread throughout a document. This is fine for hypermedia (HTML, PDF, EPUB). However, if the document is to be printed it is a very bad idea to have glossaries other than abbreviations and glossary, since a reader will not be able to locate them easily.
Both, the list of abbreviations, as well as the glossary are each defined with a glossary directive:
Source ReST markup | Rendered output |
---|---|
Abbreviations
=============
.. glossary::
|abbrr|
a black blade runner
first
see :term:`f i r s t`
and short :term:`abbrr`
|
Abbreviations |
Glossary
========
.. glossary::
abbrr
a black blade runner
some description
a black blade runner
elaborate entry for |abbrr|
f i r s t
see :term:`first`
|
Glossary |
.. |abbrr| replace:: :term:`abbrr <a black blade runner>`
|
In case of duplicate glossary terms in multiple glossaries, the last
entry wins when resolving a reference to the term. Therefore,
abbreviations should appear before the glossary. Here is an exact term
reference abbrr (:term:`abbrr`
) and an elaborate one
abbrr (.. |abbrr| replace:: :term:`tstaddr <a black blade
runner>`
).
Enable features with option –enable FLG,FLG,…:
glossary.inc
abbrevs.inc
abbrev_defs.inc