Intersphinx: allow glossary terms to be referenced by grouping key in the inventory

[jayaddison]

Describe the bug

When using the glossary directive, it's possible to add grouping keys to entries that share the same name. As a side-effect this provides a form of disambiguation.

Terminology
===========

.. glossary::

   t : physics
      A variable used to refer to ``time``.

   T : ISO
      A delimiter symbol used to separate date information from time-of-day information.

These entries currently resolve to a single (and therefore ambiguous at reference-time) entry in the Intersphinx inventory.

I think it would be possible to allow them to be referenced unambiguously -- but if acceptable, we would also need to be careful to do that in a backwards-compatible manner.

How to Reproduce

conf.py

extensions = ['sphinx.ext.intersphinx']

index.rst

.. glossary::

   t : physics
      A variable used to refer to ``time``.

   T : ISO
      A delimiter symbol used to separate date information from time-of-day information.

Repro steps (shell commands)

$ sphinx-build -b html index.rst/.. _build
$ python -m sphinx.ext.intersphinx _build/objects.inv | grep -w term
std:term
    T                                                                                : index.html#term-T
    t                                                                                : index.html#term-t

Requested It could be useful to reference each of the two glossary term definitions (T / t) individually, because the project has defined them as distinct concepts.

Current It's not possible to reference the items individually using Intersphinx, because the inventory entries' identifiers are the same when compared case-insentively.

Environment Information

Platform:              linux; (Linux-6.10.6-rt-amd64-x86_64-with-glibc2.40)
Python version:        3.12.5 (main, Aug 22 2024, 13:11:09) [GCC 14.2.0])
Python implementation: CPython
Sphinx version:        8.0.2
Docutils version:      0.21.2
Jinja2 version:        3.1.4
Pygments version:      2.18.0

Sphinx extensions

['sphinx.ext.intersphinx']

Additional context

Discovered during #12699.

[electric-coder]

It could be useful to reference each of the two glossary term definitions (T / t) individually

It certainly would be and there are plenty of examples in physics where single letter casing can be used to distinguish meanings.

because the inventory entries' identifiers are the same when compared case-insentively.

I'm wondering what could have been the motivation for case-insensitivity in intersphinx? Maybe because intersphinx artifacts could become part of the URL? But in practice they're always part of the query string?!

[jayaddison]

because the inventory entries' identifiers are the same when compared case-insentively.

I'm wondering what could have been the motivation for case-insensitivity in intersphinx? Maybe because intersphinx artifacts could become part of the URL? But in practice they're always part of the query string?!

I always seem to forget that it's only some Intersphinx entries that are resolved case-insensitively (std:label and std:term specifically).

The code contains some relevant comments -- re-reading those I infer:

• Intersphinx was, I think (but I'm not 100% sure) originally designed with entirely case-sensitive matching. However: Sphinx would emit warnings when projects defined duplicative terms (and labels?).
• However, in contrast, term definitions in Sphinx were case-insensitive -- my best-guess is that that was to make term cross-referencing slightly more convenient.
• Bugreport #7418 relates to a project that has a genuine requirement for two case-insensitively-equal strings -- MySQL and mysql -- to be defined as separate terms. As a result, term began to support -- but does not require -- case-sensitive matching.
• In #9291, Intersphinx's handling of resolution of term references was reported as inconsistent with Sphinx's internal term resolution -- and so Intersphinx resolution was adjusted to allow case-insensitive resolution.