rST: add warning about duplicate hyperlink target names

CHANGES.rst

@@ -132,7 +132,8 @@ Bugs fixed
   directly defined in certain cases, depending on autodoc processing
   order.
   Patch by Jeremy Maitin-Shepard.
-
+* #13383: Emit a warning for duplicate internal hyperlink declarations.
+  Patch by James Addison.
 
 Testing
 -------

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

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.

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.

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.

tests/test_builders/test_build_warnings.py

@@ -18,11 +18,14 @@
     from sphinx.testing.util import SphinxTestApp
 
 ENV_WARNINGS = """\
+{root}/includes/shared-hyperlinks.rst:\\d+: WARNING: duplicate label ambiguous_shared_hyperlink, other instance in {root}/hyperlinks.rst
 {root}/autodoc_fodder.py:docstring of autodoc_fodder.MarkupError:\\d+: \
 WARNING: Explicit markup ends without a blank line; unexpected unindent. \\[docutils\\]
 {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}/includes/shared-hyperlinks.rst:\\d+: WARNING: duplicate label ambiguous_shared_hyperlink, other instance in {root}/includes/shared-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 \
@@ -94,7 +97,7 @@ def test_html_warnings_exception_on_warning(app: SphinxTestApp) -> None:
         pytest.fail('Expected an exception to be raised')
     except SphinxError:
         tb = traceback.format_exc()
-        assert 'unindent_warning' in tb
+        assert 'duplicate label' in tb
         assert 'pending_warnings' not in tb