Description

picnixz

opened on Feb 22, 2025

Issue body actions

See #120650 (comment).

We use .. index:: single: uuidN and other .. index:: directives in the UUID documentation. However, the anchor is after the actual function, meaning that https://docs.python.org/3/library/uuid.html#index-6 jumps to uuid3 instead of uuid1 for instance (compare with https://docs.python.org/3/library/uuid.html#uuid.uuid1).

OTOH, we could simply remove the .. index usages but I don't remember whether they are intersphinxed or not.

cc @AA-Turner @hugovk

Linked PRs

• gh-130461: Fix locations of .. index:: directives usage in uuid docs #130468
• gh-130461: Remove unnecessary usages of .. index:: directives in Doc/library/uuid.rst #130526
• [3.12] gh-130461: Remove unnecessary usages of .. index:: directives in Doc/library/uuid.rst (#130526) #130546
• [3.13] gh-130461: Remove unnecessary usages of .. index:: directives in Doc/library/uuid.rst (#130526) #130548

Activity

1. picnixz

   added

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   on Feb 22, 2025
2. github-project-automation

   added this to docs issueson Feb 22, 2025
3. github-project-automation

   moved this to Todo in docs issueson Feb 22, 2025
4. Mr-Sunglasses commented on Feb 22, 2025

   

   Mr-Sunglasses

   on Feb 22, 2025

   Contributor

   More actions

   See #120650 (comment).

   We use .. index:: single: uuidN and other .. index:: directives in the UUID documentation. However, the anchor is after the actual function, meaning that https://docs.python.org/3/library/uuid.html#index-6 jumps to uuid3 instead of uuid1 for instance (compare with https://docs.python.org/3/library/uuid.html#uuid.uuid1).

   OTOH, we could simply remove the .. index usages but I don't remember whether they are intersphinxed or not.

   cc @AA-Turner @hugovk

   @picnixz , I've investigated this issue by removing .. index and yeah they are intersphinxed, by removing them they does not show on the index page, do I find a fix, by adding .. index above .. function:: this will fix it.
5. Mr-Sunglasses

   added a commit that references this issue on Feb 22, 2025

   pythongh-130461: Fix locations of `.. index::` directives usage in `D…

   9b0354c
6. picnixz commented on Feb 22, 2025

   

   picnixz

   on Feb 22, 2025

   MemberAuthor

   More actions

   I've investigated this issue by removing .. index and yeah they are intersphinxed, by removing them they does not show on the index page, do I find a fix, by adding .. index above .. function:: this will fix it.

   Someone might rely on them in the wild, although I doubt (because to know about it, you need to know about the RST source itself). However, there could some crawlers that do the task automatically. I don't know whether it's good or not to remove them (I feel they just duplicate the .. function:: uuid1 entry, so it's not really useful).

   Note that searching uuid1 would give you the function and not the index. The index would be at the end of the search results (see https://docs.python.org/3/search.html?q=uuid1 for instance).

   @AA-Turner do you think we can just remove those .. index::? I think it's pretty the only place in the docs where we use both an index and a function directive. Other places benefit from .. index:: as they use other search terms but in this case, I don't think it's really needed.
7. picnixz commented on Feb 22, 2025

   

   picnixz

   on Feb 22, 2025

   MemberAuthor

   More actions

   Also, the plain rendering of those indices is not really good. I think it's better to just keep the entry with (in module uuid) (this is the entry associated with .. function:: uuidX()).

   

   Reacted by Kanishk Pachauri
8. Mr-Sunglasses

   added a commit that references this issue on Feb 22, 2025

   pythongh-130461: Fix locations of `.. index::` in `getnode()`

   44e58d7
9. Mr-Sunglasses commented on Feb 22, 2025

   

   Mr-Sunglasses

   on Feb 22, 2025

   Contributor

   More actions

   Also, the plain rendering of those indices is not really good. I think it's better to just keep the entry with (in module uuid) (this is the entry associated with .. function:: uuidX()).

   

   Yes totally agree, the plain entry really looks bad, so we can totally remove it if we want, (in module uuid) entry is good and enough at all.
10. picnixz

    changed the title [-]Fix locations of `.. index::` directives usage in `Doc/library/uuid.rst`[/-] [+]Fix locations or remove usages of `.. index::` directives usage in `Doc/library/uuid.rst`[/+] on Feb 22, 2025
11. picnixz

    changed the title [-]Fix locations or remove usages of `.. index::` directives usage in `Doc/library/uuid.rst`[/-] [+]Fix locations or remove usages of `.. index::` directives in `Doc/library/uuid.rst`[/+] on Feb 22, 2025
12. hugovk commented on Feb 23, 2025

    

    hugovk

    on Feb 23, 2025

    Member

    More actions

    @AA-Turner do you think we can just remove those .. index::? I think it's pretty the only place in the docs where we use both an index and a function directive. Other places benefit from .. index:: as they use other search terms but in this case, I don't think it's really needed.

    Remove, and if anyone complains, re-add them? (aka a scream test :)
13. picnixz commented on Feb 23, 2025

    

    picnixz

    on Feb 23, 2025

    MemberAuthor

    More actions

    Ok, let's just outright remove them. Those could even be legacy added and inspired from the old LaTeX docs (though I haven't checked). @Mr-Sunglasses Could you amend your PR and simply remove the .. index:: directives please? You can also add a NEWS entry saying that the corresponding indices were removed from the intersphinx inventory just in case (that way, if people want to scream, they know on which issue to scream)
14. picnixz

    changed the title [-]Fix locations or remove usages of `.. index::` directives in `Doc/library/uuid.rst`[/-] [+]Remove unnecessary usages of `.. index::` directives in `Doc/library/uuid.rst`[/+] on Feb 23, 2025
15. Mr-Sunglasses commented on Feb 24, 2025

    

    Mr-Sunglasses

    on Feb 24, 2025

    Contributor

    More actions

    Ok, let's just outright remove them. Those could even be legacy added and inspired from the old LaTeX docs (though I haven't checked). @Mr-Sunglasses Could you amend your PR and simply remove the .. index:: directives please? You can also add a NEWS entry saying that the corresponding indices were removed from the intersphinx inventory just in case (that way, if people want to scream, they know on which issue to scream)

    Sure @picnixz I'l do it in #130526 PR :-)

    Reacted by Bénédikt Tran
16. Mr-Sunglasses

    added 3 commits that reference this issue on Feb 24, 2025

    pythongh-121970: Replace `.. coroutine{method,function}` with `:async…

    48cb5b5

    pythongh-130461: Remove unnecessary usages of .. index:: directives i…

    69ae854

    pythongh-130461: Remove unnecessary usages of `.. index::` directives…

    e6fd0d9
17. hugovk

    closed this as completedin #130526on Feb 25, 2025
18. hugovk

    added a commit that references this issue on Feb 25, 2025

    gh-130461: Remove unnecessary usages of `.. index::` directives in Do…

    85f1cc8
19. Mr-Sunglasses

    added a commit that references this issue on Feb 25, 2025

    pythongh-130461: Remove unnecessary usages of `.. index::` directives…

    dc6d1e3
20. hugovk

    added 2 commits that reference this issue on Feb 25, 2025

    [3.13] gh-130461: Remove unnecessary usages of `.. index::` directive…

    28bfc1c

    [3.12] gh-130461: Remove unnecessary usages of `.. index::` directive…

    ca9e52d

Issue actions