cpython
cpython copied to clipboard
python
Docs use deprecated Sphinx `.. index::` entries
In https://github.com/python/cpython/pull/97921#issuecomment-1269131226 @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)
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
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 https://github.com/python/cpython/pull/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 https://github.com/sphinx-doc/sphinx/pull/6970#issuecomment-605458628).
Removing https://github.com/python/cpython/labels/sprint because the issue missed the ones in 2022 and 2023.
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?
Yep! I have the other PRs staged locally but didn't want to spam with several PRs!
A
@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?
