sphinx-doc · jayaddison · Mar 1, 2025 · Mar 1, 2025 · Mar 2, 2025 · Mar 24, 2025
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -16,5 +16,8 @@ Features added
 Bugs fixed
 ----------
 
+* #13383: Emit a warning for duplicate internal hyperlink declarations.
+  Patch by James Addison.
+
 Testing
 -------
diff --git a/sphinx/domains/std/__init__.py b/sphinx/domains/std/__init__.py
@@ -962,6 +962,13 @@ def process_doc(
                     env.doc2path(self.labels[name][0]),
                     location=node,
                 )
+            elif name in self.anonlabels:
+                logger.warning(
+                    __('duplicate label %s, other instance in %s'),
+                    name,
+                    env.doc2path(self.anonlabels[name][0]),
+                    location=node,
+                )
             self.anonlabels[name] = docname, labelid
             if node.tagname == 'section':
                 title = cast('nodes.title', node[0])

diff --git a/tests/roots/test-warnings/hyperlinks.rst b/tests/roots/test-warnings/hyperlinks.rst
@@ -0,0 +1,9 @@
+:orphan:
+
+.. _ambiguous_hyperlink:
+
+This hyperlink target is declared with the same name in two files.
+
+.. include:: includes/shared-hyperlinks.rst
+
+This is one of two places where the shared-hyperlinks file is included.
diff --git a/tests/roots/test-warnings/includes/shared-hyperlinks.rst b/tests/roots/test-warnings/includes/shared-hyperlinks.rst
@@ -0,0 +1,5 @@
+:orphan:
+
+.. _ambiguous_shared_hyperlink:
+
+This hyperlink target is declared once and is included by multiple documents.
diff --git a/tests/roots/test-warnings/index.rst b/tests/roots/test-warnings/index.rst
@@ -43,3 +43,11 @@ This used to crash: :option:`&option`
 .. missing citation
 
 [missing]_ citation
+
+.. _ambiguous_hyperlink:
+
+This hyperlink target is declared with the same name in two files.
+
+.. include:: includes/shared-hyperlinks.rst
+
+This is one of two places where the shared-hyperlinks file is included.
diff --git a/tests/test_builders/test_build_warnings.py b/tests/test_builders/test_build_warnings.py
@@ -20,6 +20,7 @@
 {root}/index.rst:\\d+: WARNING: Encoding 'utf-8-sig' used for reading included \
 file '{root}/wrongenc.inc' seems to be wrong, try giving an :encoding: option \\[docutils\\]
 {root}/index.rst:\\d+: WARNING: invalid single index entry '' \\[index\\]
+{root}/index.rst:\\d+: WARNING: duplicate label ambiguous_hyperlink, other instance in {root}/hyperlinks.rst
 {root}/index.rst:\\d+: WARNING: image file not readable: foo.png \\[image.not_readable\\]
 {root}/index.rst:\\d+: WARNING: download file not readable: {root}/nonexisting.png \\[download.not_readable\\]
 {root}/undecodable.rst:\\d+: WARNING: undecodable source characters, replacing \