Doc: Glossary alphabetic order is only for English

[adorilson]

Documentation

Nowadays, the glossary is kept in alphabetical order manually. Here we have two problems:

• Eventually, the entry order is wrong ( Glossary: locale order )
• The alphabetical order is kept just in English.

I propose using Sphinx :sorted: option. The glossary will always be ordered in all languages. The two problems above will be solved.

Collateral effects:

• The two first current entry will change (>>> … → … >>>)
• Dunder entries will appear before the letter a.

I think the benefits are bigger than the collateral effects. Besides, it is so easy to implement.

Discus topic: https://discuss.python.org/t/glossary-alphabetically-ordering-for-all-language/101778/1

Linked PRs

• gh-138700: Add :sorted: option to automatically sort glossary #138708
• gh-138700: Add :sorted: option to automatically sort glossary #138711

[zware]

I'm in favor of the change.

Does Sphinx have a way to set the sort key (per language?) for a given entry, so that we could do something like sort >>> as ps1 and ... as ps2 to mitigate the identified collateral effects?

[adorilson]

I'm in favor of the change.

Does Sphinx have a way to set the sort key (per language?) for a given entry, so that we could do something like sort >>> as ps1 and ... as ps2 to mitigate the identified collateral effects?

According to Sphinx docs, we can specify "grouping key”, but I didn't understand how it works.

Alternatively, we could put the terms together:

```>>>```

```...```
Definition...

or

```>>>``` and ```...```
Definition...

Of course, it would be necessary to adapt the definition and, probably, fix some :term: around docs.

[brianschubert]

Grouped terms are sorted by the first term, so we could use those to force entries to be sorted in a certain way. For example, on its own __future__ would get sorted before a, but a group like

future statement
__future__
   Definition...

would get sorted with the other f entries.

[AA-Turner]

@corteisjr please don't open a PR before we've agreed on a plan. Also, it's polite to check with that the author of the issue didn't plan to do so themselves.

A

[corteisjr]

@AA-Turner The author share the issue in our community and invited the community to work on the issue, so I opened a PR.
If the plan change ,I will update

[adorilson]

Grouped terms are sorted by the first term, so we could use those to force entries to be sorted in a certain way. For example, on its own __future__ would get sorted before a, but a group like

future statement
__future__
   Definition...

would get sorted with the other f entries.

Initially, I thought it was a good idea, but after I realized that it "would get sorted with the other f entries." is only valid for English.

We can use it to remove dunders from the top, but the position of translations is uncertain.