Docs use deprecated Sphinx .. index:: entries

[ezio-melotti]

In #97921 (comment) @hugovk noticed that Sphinx has deprecated some of the .. index:: entry types:

module, keyword, operator, object, exception, statement, builtin
These all create two index entries. For example, module: hashlib creates the entries module; hashlib and hashlib; module. (These are Python-specific and therefore deprecated.)

Currently we are using some of those in the docs, so we have at least 3 options:

• keep using them if it's a silent deprecation with no removal plans
• reimplement them in pyspecific.py, if we want to keep use them (and if it's possible to reimplement them)
• remove them and replace them with the non-deprecated ones

(cc @AA-Turner)

Linked PRs

• GH-97950: Use new-style index directive ('module') #103996
• GH-97950: Allow translation of index directive content #104000
• [3.11] GH-97950: Allow translation of index directive content (GH-104000) #104151
• GH-97950: Use new-style index directive ('keyword') #104153
• [3.11] GH-97950: Use new-style index directive ('module') (GH-103996) #104154
• [3.11] GH-97950: Use new-style index directive ('keyword') (GH-104153) #104155
• GH-97950: Use new-style index directive ('operator') #104156
• [3.11] GH-97950: Use new-style index directive ('operator') (GH-104156) #104157
• GH-97950: Use new-style index directive ('object') #104158
• [3.11] GH-97950: Use new-style index directive ('object') (GH-104158) #104159
• GH-97950: Use new-style index directive ('exception') #104160
• [3.11] GH-97950: Use new-style index directive ('exception') (GH-104160) #104161
• GH-97950: Use new-style index directive ('statement') #104162
• [3.11] GH-97950: Use new-style index directive ('statement') (GH-104162) #104163
• GH-97950: Use new-style index directive ('builtin') #104164
• [3.11] GH-97950: Use new-style index directive ('builtin') (GH-104164) #104221
• [3.11] GH-97950: Fix old-style index directive in Doc/library/imp.rst #107246

[AA-Turner]

I want to remove them eventually, I think the best option may be (3) as index entry types are quite hard to patch into Sphinx.

A

[mmmarcos]

In principle, these deprecated index-types can all be replaced with the more generic pair index-type. However, this has already been done/attempted in #18004 and it was not merged because of a Sphinx issue : the python index-types (module, ...) are automatically translated in the index page while this is not the case when using pair: module; ...: (see sphinx-doc/sphinx#6970 (comment)).

[arhadthedev]

Removing sprint because the issue missed the ones in 2022 and 2023.

[ezio-melotti]

IIUC GH-104000 should be merged first to solve the translation issue, then #103996 can be merged, and I then more PRs should be created to fix other index directives (e.g. object: ...). Is this correct?

[AA-Turner]

Yep! I have the other PRs staged locally but didn't want to spam with several PRs!

A

[hugovk]

@AA-Turner Thanks for the PRs, all merged and backported to 3.11! Are we good to close this now or is there more to come?

[AA-Turner]

All done I believe, thanks all!

A