Better support for multiple glossaries

[shimizukawa]

You can use the glossary directive multiple times in a documentation without problems when you never define the same word twice.

This makes it possible to have a glossary with subtitles for topics eg.

I wonder if anyone ever had the need to put more than one glossary into the documentation. Maybe domain specific glossaries? One for math terms and one for chemical terms.

If this is a realistic usecase it would be nice to label the glossaries so that I can specify where a term belongs to. Maybe some kind of indicator as we use with the domains.

Example:

#!rst

.. glossary:: math

   term
      (definition)

This is a :math:term:`term`for my math specific glossary

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/1399
• Originally reported by: Jan Ulrich Hasecke
• Originally created at: 2014-02-19T13:08:39.295

[ghost]

Here's a use-case (mine!) that you can consider as part of this enhancement. I have a common glossary for use across multiple documents. Sometimes I want to add one or more terms to this without editing the common glossary. Although I can add another glossary:: directive, the added terms are not part of the main (:sorted:) glossary directive. I'd like to be able to somehow include additional terms, which then are sorted along with the common set. Attached shows better what I mean, containing two separate glossary directives, the intention being that the resulting single glossary listing shows as one combined sorted list (which it doesn't!). index.txt TIA

[christophercrouzet]

To add to this issue, I'm currently writing a page with a list of categories and their definitions. I thought that the glossary directive would be a good fit since, as per its dictionary definition, I indeed have “an alphabetical list of words relating to a specific subject, text, or dialect, with explanations”. On top of that, the glossary directive makes it easy to link individually to each category. But then what if I end up writing an other glossary to globally define some terms?

[LuckyResistor]

I'm writing extensive documentation using sphinx. Some commonly used modules are included as shared resources into these documentations. Having glossaries in this included documentation would help a lot. At the moment, this is not possible, because terms used in these included parts can always cause conflicts.

I see two simple solutions:

• Merging glossary terms from multiple sources into one central glossary with priorities.
• Allow separate glossaries with an additional identifier.

Reasons for Multiple Glossaries

• Extensive documentation covering different fields with conflicting terminologies (design, math, coding). The same term has a different meaning in different parts of the documentation.
• Modular documentation with inserted documentation parts. E.g. three applications use the same library to provide some functionality. The documentation for this functionality is included in the documentation of the main application.

Merging with Priorities

.. glossary::
    :priority: secondary

    term
        Secondary definition

    foo
        Foo definition

.. glossaty::
    :priority: main

    term
        Primary definition

    bar
        Bar definition

Result

term Primary definition

bar Bar definition

foo Foo definition

Secondary definitions are never rendered at the original place where they are defined but in the main glossary.

Separate Glossaries with Identifiers

Text with own :term:`terms<myid:term>`

.. glossary:: myid

    term
        Term definition

[arwedus]

In a large project, we have:

• one glossary for administrative terms
• one glossary for common (project wide) definitions
• one glossary for process, method and tools stuff
• one glossary for test terminology
• one glossary for each subsystem

A term must only appear once in one of those glossaries. What I am looking for is a "glossary of glossaries" page, i.e. a merged glossary term index. Is that possible with Sphinx as of today?