rST: add notice about duplicate hyperlink target names #13400

jayaddison · 2025-03-01T13:42:04Z

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

[skip ci]

jayaddison · 2025-03-01T22:52:30Z

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.

…tions Re-uses some existing filtering for footnotes and other acceptable duplicates. Some false-positives continue to occur with this change in place; for example, internal hyperlink targets that are subsequently `include`d into other docs.

jayaddison · 2025-03-17T12:51:19Z

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 · 2025-03-24T12:52:31Z

tests/roots/test-warnings/includes/shared-hyperlinks.rst

+.. _ambiguous_shared_hyperlink:
+
+This hyperlink target is declared once and is included by multiple documents.


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

…arget-warning

gmilde · 2025-05-21T07:39:28Z

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 · 2025-05-21T09:22:01Z

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

gmilde · 2025-05-21T11:01:09Z

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

jayaddison · 2025-05-21T11:07:45Z

Thank you; updated.

gmilde · 2025-05-21T11:12:18Z

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

…arget-warning Conflicts: CHANGES.rst

…arget-warning

jayaddison · 2025-11-29T15:08:38Z

@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 · 2025-11-29T17:13:14Z

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.

…arget-warning Conflicts: CHANGES.rst

AA-Turner · 2025-11-29T22:03:01Z

tests/test_builders/test_build_warnings.py


-ENV_WARNINGS = """\
-{root}/autodoc_fodder.py:docstring of autodoc_fodder.MarkupError:\\d+: \
+DUPLICATE_LABEL_WARNINGS = False


@jayaddison perhaps just remove this? We can add it if/when the message is upgraded to a warning.

@AA-Turner debatable, I admit - but I opted to prefer projecting the test coverage unchanged into the future, since the output seems reasonably unlikely to differ, and the rework involved could be an annoyance for someone (likely myself). It'd also provide a little more reassurance to someone inspecting a diff (again, sometimes myself in other contexts) that the author did in fact at least add test coverage.

As a first preference instead of removing it entirely, I think I'd prefer to figure out whether there's a more maintainer-friendly way to express it (e.g. some mild misuse of deprecation patterns, or similar).

@jayaddison happy for you to have a look, but otherwise I'd prefer to remove it as dead code.

A

My previous comments were word salad; I think what I should have explained up-front is: I do want this to become a warning, and I am fairly adamant about that.

So I would like to write the tests in a way that prepares for warning-level messages, while permitting info-level until then.

I'm still on the fence about making this a warning. I opened #14187 as an idea that would give me more certainty, but that's a large project.

My one and only Linux kernel patch (so far, at least) disambiguated two duplicate labels, and that allowed the documentation to build reproducibly. If at all possible, I'd prefer for that not to regress (I don't anticipate that that exact label would be re-duplicated, but the same category of label-duplication problem could easily occur again elsewhere in the documentation).

(I do also agree with providing advance notice and a gradual rollout though, given uncertainty about the scale of the problem)

Actually, I lie - my patch was one of a few fixes that has improved the reproducibility of the Linux kernel docs, but there is at least one other remaining nondeterminism issue in Sphinx that is relevant there.

AA-Turner · 2025-11-30T00:49:13Z

tests/test_builders/test_build_warnings.py

+if version_info >= (11, 0, 0):
+    # this code can be removed when we prepare Sphinx 11 for release
+    msg = 'From Sphinx 11, duplicate labels should always warn by default'
+    raise RemovedInSphinx11Warning(msg)
+else:
+    DUPLICATE_LABEL_WARNINGS = version_info >= (10, 0, 0)


This isn't the right approach: we shouldn't raise warnings as exceptions, nor does it make sense to raise a module-level warning in a test file.

It doesn't make sense, but it would only occur when we begin developing Sphinx 11 -- the major release after the info-level messages are upgraded to warnings. At that point, the test condition could be removed.

What's a better way to annotate test code that can be cleaned up after a certain version?

What's a better way to annotate test code that can be cleaned up after a certain version?

# xref RemovedInSphinxXXWarning

Whoever does the removals needs to search for the relevant name, so we often put things in comments.

Ok, perfect. I'll adjust the test code to follow that pattern. Thank you!

AA-Turner · 2025-11-30T06:23:10Z

I'm going to delay this to 9.1.

A

…arget-warning Conflicts: CHANGES.rst

…warnings

tests/test_builders/test_build_warnings.py

jayaddison · 2025-12-21T11:40:03Z

@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 added 2 commits March 1, 2025 13:38

rST: add warning about duplicate anonymous hyperlink targets

4df6239

Add CHANGES.rst entry

2dcdbce

[skip ci]

AA-Turner added this to the 8.3.0 milestone Mar 1, 2025

jayaddison marked this pull request as draft March 1, 2025 22:52

jayaddison added 2 commits March 24, 2025 11:59

Merge branch 'master' into warn-about-duplicate-anonymous-hyperlinks

e98d5b4

Tests: add an anonymous hyperlink included from multiple documents

f95f62e

jayaddison commented Mar 24, 2025

View reviewed changes

Merge branch 'master' into issue-13383/duplicate-internal-hyperlink-t…

0a93fa4

…arget-warning

jayaddison changed the title ~~rST: add warning about duplicate anonymous hyperlink targets~~ rST: add warning about duplicate-declaration hyperlink targets May 21, 2025

jayaddison changed the title ~~rST: add warning about duplicate-declaration hyperlink targets~~ rST: add warning about duplicate hyperlink target names May 21, 2025

jayaddison added 3 commits June 2, 2025 20:49

Merge branch 'master' into issue-13383/duplicate-internal-hyperlink-t…

5f9b703

…arget-warning Conflicts: CHANGES.rst

tests: build-warnings: fix shared-hyperlink warning match expectations

5edb56d

tests: build-warnings: adjust expected exception-raiser warning message

f54dc08

jayaddison marked this pull request as ready for review August 2, 2025 09:49

jayaddison added 2 commits October 15, 2025 10:45

Merge branch 'master' into issue-13383/duplicate-internal-hyperlink-t…

f78dff0

…arget-warning

Merge branch 'master' into issue-13383/duplicate-internal-hyperlink-t…

4f3bf7f

…arget-warning

AA-Turner modified the milestones: 8.3.0, 9.0.0 Nov 25, 2025

AA-Turner requested changes Nov 29, 2025

View reviewed changes

rST: remove duplicate anonymous label from warn to info severity

07b5ed7

jayaddison added 2 commits November 29, 2025 17:28

Merge branch 'master' into issue-13383/duplicate-internal-hyperlink-t…

ea23ca8

…arget-warning Conflicts: CHANGES.rst

Apply ruff format

69b53bc

jayaddison mentioned this pull request Nov 29, 2025

9.0.0 release plan #14092

Closed

AA-Turner reviewed Nov 29, 2025

View reviewed changes

AA-Turner added the awaiting:response Waiting for a response from the author of this issue label Nov 30, 2025

Adapt test case to anticipated feature rollout schedule

a3335e9

jayaddison changed the title ~~rST: add warning about duplicate hyperlink target names~~ rST: add notice about duplicate hyperlink target names Nov 30, 2025

AA-Turner reviewed Nov 30, 2025

View reviewed changes

AA-Turner modified the milestones: 9.0.0, 9.x Nov 30, 2025

jayaddison added 2 commits December 16, 2025 22:11

Merge branch 'master' into issue-13383/duplicate-internal-hyperlink-t…

accc8cf

…arget-warning Conflicts: CHANGES.rst

Tests: apply a more sensible deprecation strategy to duplicate-label …

316124a

…warnings

AA-Turner mentioned this pull request Dec 16, 2025

Create a mypy-primer like workflow in CI for Sphinx #14187

Open

Tests: typo/syntax fixups in comment

74f0e01

jayaddison commented Dec 16, 2025

View reviewed changes

tests/test_builders/test_build_warnings.py Show resolved Hide resolved

Tests: retain unindent_warning test coverage

cdbf375

		.. _ambiguous_shared_hyperlink:

		This hyperlink target is declared once and is included by multiple documents.

Uh oh!

rST: add notice about duplicate hyperlink target names #13400

Are you sure you want to change the base?

rST: add notice about duplicate hyperlink target names #13400

Conversation

jayaddison commented Mar 1, 2025

Purpose

References

Uh oh!

jayaddison commented Mar 1, 2025

Uh oh!

jayaddison commented Mar 17, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gmilde commented May 21, 2025

Uh oh!

jayaddison commented May 21, 2025

Uh oh!

gmilde commented May 21, 2025

Uh oh!

jayaddison commented May 21, 2025

Uh oh!

gmilde commented May 21, 2025

Uh oh!

jayaddison commented Nov 29, 2025

Uh oh!

AA-Turner left a comment

Choose a reason for hiding this comment

Uh oh!

jayaddison commented Nov 29, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AA-Turner commented Nov 30, 2025

Uh oh!

Uh oh!

jayaddison commented Dec 21, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants