sphinx-doc
rST: add notice about duplicate hyperlink target names
Purpose
The goal of this pull request is to identify duplicate internal hyperlink targets -- the presence of these can cause documentation hyperlinks to resolve ambiguously (e.g. sometimes incorrectly) at build-time.
References
- Resolves #13383
The changes in 4df623900b0715f04376d7cadca8f8f01f0220c6 seem to introduce a large number of false-positive warnings; numbered footnotes, for example, are frequently a source of distraction with this in place. I'll move this pull request back into draft status until I can resolve that problem.
Todo: extend the test coverage to add an example of document that is include'd into more than one other location; this appears to be another case where the same symptom (ambiguous resolution of anonymous hyperlinks) can occur.
The term "anonymous" in the name of this PR is confusing:
The goal of this pull request is to identify duplicate internal hyperlink targets [...]
Anonymous hyperlink targets don't use a reference name and may be internal or external. Example:
See `the web site`__ of my `favorite programming language`__.
__ https://www.python.org
__ Why I like Python_
Why I like Python
*****************
its nice
In every document, the number of anonymous references must match the number of anonymous targets.
Duplicate anonymous hyperlink targets would be a bug in the assignment of IDs to their <target> elements.
Thank you @gmilde - is edited version (rST: add warning about duplicate-declaration hyperlink targets) reasonably accurate?
Regarding spurious warnings, see also my comment on the issue page. https://github.com/sphinx-doc/sphinx/issues/13383#issuecomment-2872393837
@AA-Turner thanks for adding the 9.0.0 milestone - I worry about the potential for this to cause build breakage for potentially lots of downstream Sphinx projects, but I would also like for it to be included in an upcoming release.
Seems reasonable, yep. Perhaps I'll mention it on the release thread too for inclusion, just in case anyone feels like testing it (or at least being aware of it) in advance.
