Intersphinx: log warnings for ambiguous target resolutions. (#12329)

This commit adds detection of ambiguous ``std:label`` and ``std:term`` references (due to case-insensitivity)
during loading and resolution of Intersphinx targets,
and emits a warning if found.

Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Co-authored-by: Chris Sewell <chrisj_sewell@hotmail.com>

tests/test_extensions/test_ext_intersphinx.py

@@ -19,7 +19,11 @@ from sphinx.ext.intersphinx import setup as intersphinx_setup
 from sphinx.ext.intersphinx._load import _get_safe_url, _strip_basic_auth
 from sphinx.util.console import strip_colors
 
-from tests.test_util.intersphinx_data import INVENTORY_V2, INVENTORY_V2_NO_VERSION
+from tests.test_util.intersphinx_data import (
+    INVENTORY_V2,
+    INVENTORY_V2_AMBIGUOUS_TERMS,
+    INVENTORY_V2_NO_VERSION,
+)
 from tests.utils import http_server
 
 
@@ -247,6 +251,24 @@ def test_missing_reference_stddomain(tmp_path, app, status, warning):
     assert rn.astext() == 'The Julia Domain'
 
 
+def test_ambiguous_reference_warning(tmp_path, app, warning):
+    inv_file = tmp_path / 'inventory'
+    inv_file.write_bytes(INVENTORY_V2_AMBIGUOUS_TERMS)
+    set_config(app, {
+        'cmd': ('https://docs.python.org/', str(inv_file)),
+    })
+
+    # load the inventory
+    normalize_intersphinx_mapping(app, app.config)
+    load_mappings(app)
+
+    # term reference (case insensitive)
+    node, contnode = fake_node('std', 'term', 'A TERM', 'A TERM')
+    missing_reference(app, app.env, node, contnode)
+
+    assert 'multiple matches found for std:term:A TERM' in warning.getvalue()
+
+
 @pytest.mark.sphinx('html', testroot='ext-intersphinx-cppdomain')
 def test_missing_reference_cppdomain(tmp_path, app, status, warning):
     inv_file = tmp_path / 'inventory'

tests/test_util/intersphinx_data.py

@@ -50,3 +50,13 @@ INVENTORY_V2_NO_VERSION: Final[bytes] = b'''\
 ''' + zlib.compress(b'''\
 module1 py:module 0 foo.html#module-module1 Long Module desc
 ''')
+
+INVENTORY_V2_AMBIGUOUS_TERMS: Final[bytes] = b'''\
+# Sphinx inventory version 2
+# Project: foo
+# Version: 2.0
+# The remainder of this file is compressed with zlib.
+''' + zlib.compress(b'''\
+a term std:term -1 glossary.html#term-a-term -
+A term std:term -1 glossary.html#term-a-term -
+''')

tests/test_util/test_util_inventory.py

@@ -10,6 +10,7 @@ from sphinx.util.inventory import InventoryFile
 from tests.test_util.intersphinx_data import (
     INVENTORY_V1,
     INVENTORY_V2,
+    INVENTORY_V2_AMBIGUOUS_TERMS,
     INVENTORY_V2_NO_VERSION,
 )
 
@@ -48,6 +49,13 @@ def test_read_inventory_v2_not_having_version():
         ('foo', '', '/util/foo.html#module-module1', 'Long Module desc')
 
 
+def test_ambiguous_definition_warning(warning):
+    f = BytesIO(INVENTORY_V2_AMBIGUOUS_TERMS)
+    InventoryFile.load(f, '/util', posixpath.join)
+
+    assert 'contains multiple definitions for std:term:a' in warning.getvalue().lower()
+
+
 def _write_appconfig(dir, language, prefix=None):
     prefix = prefix or language
     os.makedirs(dir / prefix, exist_ok=True)