Support for Glossary Identifiers

[Arsha-M]

Feature or Bugfix

• Feature

Purpose

• Currently, Sphinx supports multiple glossaries, but the same term cannot appear twice. This is improved by adding an identifier to glossaries so that the correct glossary can be referenced.

Detail

• Added the identifier to the glossary directive
• Added documentation
• Added testing

Relates

• Closes #1399

[Arsha-M]

Hello! I believe that I am ready for the workflows to be run and for a review. :)

I successfully ran the linter, unit tests, and documentation locally. However, I am sure that I made a mistake somewhere as this is my first contribution.

I don't understand how the i18n.py module works so in the make_glossary_term() call, I passed an empty string as the key. Is this correct?

Also, are you happy with the referencing of the terms? Here is an example of what it looks like:

The source to produce this is:

[Arsha-M]

Hello @AA-Turner, gentle ping. I noticed that you have been making most of the merges recently, and I was wondering if I could get approval for running the workflows and a review? 🙏

Thanks!

[Arsha-M]

Hello @AA-Turner, gentle ping. Would I be able to get some feedback on these changes? 🙏

Thanks!

[AA-Turner]

I can review the change, but I want to review the discussion on the overall design first.

A

[tk0miya]

I think a title of reference and an index entry should be bare "Term1".

[shimizukawa]

Here is a summary of my opinion.

1. Sometime I also want to have a type for the term and allow a term with the same name for each type.
2. In articles, display terms of the same name as they are.
3. In the Index, display terms of the same name with separated entries so that they are indistinguishable from each other.

In the index, for example, separated entries as:

term (type1)
term (type2)

or pair style as:

term
    type1
    type2

[Arsha-M]

Thanks for the feedback @tk0miya @shimizukawa

I would like to summarize the requested changes before I make them:

1. Instead of calling it a glossary "key" change it to "classifier".
2. Improve the documentation
3. Make it so that the index shows the terms with the different types in a nicer format. as suggested by @shimizukawa
4. Fix the behavior of the optional_arguments in a manner that @tk0miya suggests.
5. Improve the way that the "classifier" and term are stored in the domain database.

Thanks again for your feedback, I greatly appreciate it.

[Arsha-M]

I think a title of reference and an index entry should be bare "Term1".

Whenever you say "title of reference" do you mean when you do :term:`page2:Term2` , you would like it to be rendered as "Term2" instead of "page2:Term2"?

Alternatively, are you okay with it being rendered as "page2:Term2" by default and require the user to do :term:`Term2 <page2:Term2>` ?

[n-peugnet]

@shimizukawa:

3. In the Index, display terms of the same name with separated entries so that they are indistinguishable from each other.

In the index, for example, separated entries as:

term (type1)
term (type2)

or pair style as:

term
    type1
    type2

IMO the pair style would be perfect. This would also generate these entries:

type1
    term
type2
    term

But I would like to be able to translate type1 and type2 in other languages.