Warning about duplicate definitions in intersphinx mapping

[maxnoe]

Describe the bug

We recently started getting warnings about duplicate definition in intersphinx, from two upstream projects:

• sklearn, see BUG: Stable docs intersphinx has a duplicate std:term:y scikit-learn/scikit-learn#29337
• ipywidgets, see Intersphinx warning: multiple definitions for std:label:examples/Widget Layout.ipynb#display jupyter-widgets/ipywidgets#3930

Sklearn maintainers suspect this to be a sphinx bug, so I am opening this issue here.

How to Reproduce

$ pip list | grep  Sphinx
Sphinx                        7.4.2
$ python -m sphinx.ext.intersphinx https://scikit-learn.org/stable/objects.inv | grep "    y "
WARNING:sphinx.sphinx.util.inventory:inventory <> contains multiple definitions for std:term:y
    y        

and

$ python -m sphinx.ext.intersphinx https://ipywidgets.readthedocs.io/en/stable/objects.inv | grep 'Widget Layout.ipynb#display'
WARNING:sphinx.sphinx.util.inventory:inventory <> contains multiple definitions for std:label:examples/Widget Layout.ipynb#display
    examples/Widget Layout.ipynb#display     display                                 : examples/Widget%20Layout.html#id1

Environment Information

Sphinx 7.4.2

Sphinx extensions

intersphinx

Additional context

No response

[lesteve]

The warning seems to happen in sphinx 7.4.0 and not 7.3.7, not sure if this is because our (scikit-learn) objects.inv has always been problematic somehow and sphinx 7.4.0 only started warning about it ...

In case there is something we can do on the scikit-learn side, let us know ...

[AA-Turner]

Thank you for opening this Max (@maxnoe). This was introduced in 799ae16 (#12329). You can suppress it with 'intersphinx.external' in your suppress_warnings, though the warning is alerting you to that intersphinx has encountered an ambiguity in resolution.

The issue with sklearn is that you have both :term:`y` and :term:`Y` defined in the glossary:

https://github.com/scikit-learn/scikit-learn/blob/d79cb58c464f0b54bf0f0286c725d2df837574d0/doc/glossary.rst?plain=1#L1891-L1898

The issue with ipywidgets is that the page has two "Display" headings, one capitalised and one uncapitalised (this is mainly an educated guess as it also depends on how the ipynb file is parsed in to Sphinx):

https://github.com/jupyter-widgets/ipywidgets/blob/main/docs/source/examples/Widget%20Layout.ipynb

A

[jayaddison]

Author of this added warning logic here; apologies for the distraction caused.

I think that the Y / y case in scikit seems like a false-positive, because the duplicate definitions both refer to the same entity -- yes, the resolution is ambiguous, but the resolution result is the same in both cases.

The ipywidgets case also seems somewhat noisy to warn about.. however there are genuinely two different hyperlink definitions that can be resolved-to in that case (examples/Widget%20Layout.html#id1 display and examples/Widget%20Layout.html#display Display).

I'll spend some time to figure out whether we can filter out the first case without affecting the second.

[jayaddison]

Note: although not (yet?) reported here, I think these cases would also emit warnings during some Intersphinx refeerence resolution code:

sphinx/sphinx/ext/intersphinx/_resolve.py

Lines 83 to 87 in c4a7f5b

	if len(insensitive_matches) > 1:
	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)

[AA-Turner]

Sphinx 7.4.4 has been released with a fix.

A