Intersphinx lookups: log warnings for ambiguous target definitions and resolutions.

sphinx/ext/intersphinx/_resolve.py

@@ -80,6 +80,13 @@ def _resolve_reference_in_domain_by_target(
             target_lower = target.lower()
             insensitive_matches = list(filter(lambda k: k.lower() == target_lower,
                                               inventory[objtype].keys()))
+            if len(insensitive_matches) > 1:
+                LOGGER.warning(
+                    f"{domain.name}: multiple matches found for {objtype}:{target}",
+                    type='intersphinx',
+                    subtype='external',
+                    location=node,
+                )
             if insensitive_matches:
                 data = inventory[objtype][insensitive_matches[0]]
             else:

tests/test_extensions/test_ext_intersphinx.py

@@ -247,6 +247,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)
+    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

@@ -32,6 +32,7 @@
 foons cpp:type 1 index.html#foons -
 foons::bartype cpp:type 1 index.html#foons_bartype -
 a term std:term -1 glossary.html#term-a-term -
+A term std:term -1 glossary.html#term-a-term -
 ls.-l std:cmdoption 1 index.html#cmdoption-ls-l -
 docname std:doc -1 docname.html -
 foo js:module 1 index.html#foo -