rST: add notice about duplicate hyperlink target names

[jayaddison]

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 Possible bug: duplicate rST hyperlink targets don't appear to emit a warning during project processing? #13383

[jayaddison]

The changes in 4df6239 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.

[jayaddison]

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.

[jayaddison]

@AA-Turner @picnixz is there a way to determine a unique declaration identifier/path -- e.g. where a hyperlink was defined, instead of where it is used?

When reporting warnings about duplicated anonymous hyperlinks, it'd be nice to be able to indicate clearly that the duplication originates from multiple includes of a common document, instead of weird/confusing warnings about the hyperlinks appearing in multiple documents.

[gmilde]

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.

[jayaddison]

Thank you @gmilde - is edited version (rST: add warning about duplicate-declaration hyperlink targets) reasonably accurate?

[gmilde]

I'd call it "rST: add warning about duplicate hyperlink target names".

[jayaddison]

Thank you; updated.

[gmilde]

Regarding spurious warnings, see also my comment on the issue page.
#13383 (comment)

[jayaddison]

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

[AA-Turner]

Can we use an INFO level notice for now, and add a note to upgrade it to WARNING in eg Sphinx 11?

A

[jayaddison]

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.

[AA-Turner]

I'm going to delay this to 9.1.

A

[jayaddison]

@AA-Turner this is probably too late for the 9.1.0 boat (I notice the rc1 ship has sailed), but should be ready for review.

[jayaddison]

I'm uncomfortable with the way that I offensively dismissed what I felt to be a spammy issue request about AI in an unrelated FOSS project thread yesterday (2026-02-14). I mention this in case you'd prefer not to accept my contributions; however you are still welcome to. I don't use AI myself and would like not to be critical of those who do, but I was angry.

cc @AA-Turner @picnixz @francoisfreitag @danieleades (I'm not going to repost this on all five of the threads I have option, but do want to make you aware)