rST: add notice about duplicate hyperlink target names

CHANGES.rst

@@ -19,6 +19,9 @@ Features added
 
 Bugs fixed
 ----------
+* #13383: Emit an info-level message about duplicate internal hyperlink
+  declarations.
+  Patch by James Addison.
 
 Testing
 -------

sphinx/domains/std/__init__.py

@@ -963,6 +963,13 @@ def process_doc(
                     env.doc2path(self.labels[name][0]),
                     location=node,
                 )
+            elif name in self.anonlabels:
+                logger.info(
+                    __('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

@@ -8,6 +8,7 @@
 
 import pytest
 
+from sphinx import version_info
 from sphinx._cli.util.errors import strip_escape_sequences
 from sphinx.errors import SphinxError
 
@@ -17,15 +18,35 @@
 
     from sphinx.testing.util import SphinxTestApp
 
-ENV_WARNINGS = """\
-{root}/autodoc_fodder.py:docstring of autodoc_fodder.MarkupError:\\d+: \
+# xref RemovedInSphinx11Warning
+# From Sphinx 10, duplicate labels should always warn by default
+DUPLICATE_LABEL_WARNINGS = version_info >= (10, 0, 0)
+
+ENV_WARNINGS = (
+    (
+        """
+{root}/includes/shared-hyperlinks.rst:\\d+: WARNING: duplicate label ambiguous_shared_hyperlink, other instance in {root}/hyperlinks.rst
+"""
+        if DUPLICATE_LABEL_WARNINGS
+        else ''
+    )
+    + """{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: 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"""
+        if DUPLICATE_LABEL_WARNINGS
+        else ''
+    )
+    + """
 {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\\]
 """
+)
 
 HTML_WARNINGS = (
     ENV_WARNINGS
@@ -94,6 +115,7 @@ def test_html_warnings_exception_on_warning(app: SphinxTestApp) -> None:
         tb = traceback.format_exc()
         assert 'unindent_warning' in tb
         assert 'pending_warnings' not in tb
+        assert 'duplicate label' in tb or not DUPLICATE_LABEL_WARNINGS
 
 
 @pytest.mark.sphinx(