Repository navigation
Docs use deprecated Sphinx .. index:: entries #97950
Description
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
Activity
AA-Turner commentedon Oct 13, 2022
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 commentedon Jan 26, 2023
In principle, these deprecated index-types can all be replaced with the more generic
pairindex-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 usingpair: module; ...: (see sphinx-doc/sphinx#6970 (comment)).30 remaining items
[3.11] GH-97950: Use new-style index directive ('exception') (GH-104160…
pythonGH-97950: Use new-style index directive ('statement') (pythonGH…
[3.11] GH-97950: Use new-style index directive ('statement') (GH-104162…
GH-97950: Use new-style index directive ('builtin') (#104164)
pythonGH-97950: Use new-style index directive ('builtin') (pythonGH-1…
[3.11] GH-97950: Use new-style index directive ('builtin') (GH-104164) (
hugovk commentedon May 6, 2023
@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 commentedon May 6, 2023
All done I believe, thanks all!
A
pythonGH-97950: Use new-style index directive ('builtin') (python#104164
[3.11] GH-97950: Fix old-style index directive in Doc/library/imp.rst (…