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

sphinx/ext/intersphinx/_resolve.py

@@ -15,6 +15,7 @@
 from sphinx.ext.intersphinx._shared import LOGGER, InventoryAdapter
 from sphinx.locale import _, __
 from sphinx.transforms.post_transforms import ReferencesResolver
+from sphinx.util import logging
 from sphinx.util.docutils import CustomReSTDispatcher, SphinxRole
 
 if TYPE_CHECKING:
@@ -30,6 +31,8 @@
     from sphinx.environment import BuildEnvironment
     from sphinx.util.typing import Inventory, InventoryItem, RoleFunction
 
+logger = logging.getLogger(__name__)
+
 
 def _create_element_from_result(domain: Domain, inv_name: str | None,
                                 data: InventoryItem,
@@ -80,6 +83,8 @@
             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}")
             if insensitive_matches:
                 data = inventory[objtype][insensitive_matches[0]]
             else:

tests/test_extensions/test_ext_intersphinx.py

@@ -2,6 +2,7 @@
 
 import http.server
 from unittest import mock
+from warnings import catch_warnings
 
 import pytest
 from docutils import nodes
@@ -247,6 +248,24 @@
     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 -