Remove unnecessary usages of .. index:: directives in Doc/library/uuid.rst

[picnixz]

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

[Mr-Sunglasses]

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.

[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.

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.

[picnixz]

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()).

[Mr-Sunglasses]

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.

[hugovk]

@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 :)

[picnixz]

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)

[Mr-Sunglasses]

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 :-)