intersphinx: Reduce log message severity when ambiguous target resolves to a duplicate

CHANGES.rst

@@ -29,6 +29,10 @@ Bugs fixed
   so that it now runs after the docutils ``Footnotes`` resolution transform.
   Patch by Chris Sewell.
 
+* #12587: Do not warn when potential ambiguity detected during Intersphinx
+  resolution occurs due to duplicate targets that differ case-insensitively.
+  Patch by James Addison.
+
 Testing
 -------
 

sphinx/ext/intersphinx/_resolve.py

@@ -82,10 +82,16 @@ def _resolve_reference_in_domain_by_target(
             insensitive_matches = list(filter(lambda k: k.lower() == target_lower,
                                               inventory[objtype].keys()))
             if len(insensitive_matches) > 1:
+                data_items = {inventory[objtype][match] for match in insensitive_matches}
                 inv_descriptor = inv_name or 'main_inventory'
-                LOGGER.warning(__("inventory '%s': multiple matches found for %s:%s"),
-                               inv_descriptor, objtype, target,
-                               type='intersphinx',  subtype='external', location=node)
+                if len(data_items) == 1:  # these are duplicates; relatively innocuous
+                    LOGGER.debug(__("inventory '%s': duplicate matches found for %s:%s"),
+                                 inv_descriptor, objtype, target,
+                                 type='intersphinx',  subtype='external', location=node)
+                else:
+                    LOGGER.warning(__("inventory '%s': multiple matches found for %s:%s"),
+                                   inv_descriptor, 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

@@ -313,7 +313,14 @@ def test_missing_reference_stddomain(tmp_path, app):
     assert rn.astext() == 'The Julia Domain'
 
 
-def test_ambiguous_reference_warning(tmp_path, app):
+@pytest.mark.parametrize(
+    ('term', 'expected_ambiguity'),
+    [
+        ('A TERM', False),
+        ('B TERM', True),
+    ],
+)
+def test_ambiguous_reference_handling(term, expected_ambiguity, tmp_path, app, warning):
     inv_file = tmp_path / 'inventory'
     inv_file.write_bytes(INVENTORY_V2_AMBIGUOUS_TERMS)
     set_config(
@@ -328,10 +335,11 @@ def test_ambiguous_reference_warning(tmp_path, app):
     load_mappings(app)
 
     # term reference (case insensitive)
-    node, contnode = fake_node('std', 'term', 'A TERM', 'A TERM')
+    node, contnode = fake_node('std', 'term', term, term)
     missing_reference(app, app.env, node, contnode)
 
-    assert 'multiple matches found for std:term:A TERM' in app.warning.getvalue()
+    ambiguity = f'multiple matches found for std:term:{term}' in warning.getvalue()
+    assert ambiguity is expected_ambiguity
 
 
 @pytest.mark.sphinx('html', testroot='ext-intersphinx-cppdomain')