HTML: Assign glossary terms with grouping keys to single-character groupings

CHANGES.rst

@@ -96,6 +96,10 @@ Bugs fixed
   file URL (user-defined base URL of an intersphinx project are left untouched
   even if they end with double forward slashes).
   Patch by Bénédikt Tran.
+* #12707: HTML: Fix a bug where the grouping keys (categories) used in
+  glossaries would be used instead of the expected single-character groupings
+  displayed for all other index entries.
+  Patch by James Addison.
 
 Testing
 -------

sphinx/environment/adapters/indexentries.py

@@ -82,6 +82,9 @@ def create_index(
                         except ValueError:
                             entry, = _split_into(1, 'single', value)
                             sub_entry = ''
+                        if category_key and not entry.startswith(category_key):
+                            # TODO: can sub_entry be non-empty here?  under what conditions?
+                            entry, sub_entry = category_key, entry
                         _add_entry(entry, sub_entry, main,
                                    dic=new, link=uri, key=category_key)
                     elif entry_type == 'pair':
@@ -219,7 +222,7 @@ def _group_by_func(entry: tuple[str, _IndexEntry]) -> str:
     key, (targets, sub_items, category_key) = entry
 
     if category_key is not None:
-        return category_key
+        key = category_key
 
     # now calculate the key
     if key.startswith('\N{RIGHT-TO-LEFT MARK}'):

tests/roots/test-glossary/index.rst

@@ -10,9 +10,9 @@ test-glossary
    *fermion*
       Particle with half-integer spin.
 
-   tauon
-   myon
-   electron
+   tauon : fermions
+   myon : fermions
+   electron : fermions
       Examples for fermions.
 
    über

tests/roots/test-root/markup.txt

@@ -360,9 +360,9 @@ This tests :CLASS:`role names in uppercase`.
    *fermion*
       Particle with half-integer spin.
 
-   tauon
-   myon
-   electron
+   tauon : fermions
+   myon : fermions
+   electron : fermions
       Examples for fermions.
 
    über

tests/test_builders/test_build_html_5_output.py

@@ -8,14 +8,28 @@
 import pytest
 from docutils import nodes
 
+from sphinx import locale
+
 from tests.test_builders.xpath_util import check_xpath
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterable
+    from collections.abc import Callable, Iterable, Sequence
     from typing import Literal
     from xml.etree.ElementTree import Element
 
 
+def _symbolic_link_check(nodes: Sequence[Element]) -> None:
+    """Confirm that a series of nodes are HTML hyperlinks represented by individual symbols"""
+    assert nodes, 'Expected at least one node to check'
+    _ = locale.get_translation('sphinx')
+    for idx, node in enumerate(nodes):
+        assert node.tag == 'a', 'Attempted to check hyperlink on a non-anchor element'
+        hyperlink_label = ''.join(node.itertext())
+        if idx == 0 and hyperlink_label == _('Symbols'):
+            continue  # allow the first label to be a named group of symbols
+        assert len(hyperlink_label) == 1
+
+
 def tail_check(check: str) -> Callable[[Iterable[Element]], Literal[True]]:
     rex = re.compile(check)
 
@@ -481,6 +495,7 @@ def checker(nodes: Iterable[Element]) -> Literal[True]:
         ('genindex.html', './/a/strong', 'Other'),
         ('genindex.html', './/a', 'entry'),
         ('genindex.html', './/li/a', 'double'),
+        ('genindex.html', './/div[@class="genindex-jumpbox"]/a', _symbolic_link_check),
         ('otherext.html', './/h1', 'Generated section'),
         ('otherext.html', ".//a[@href='_sources/otherext.foo.txt']", ''),
         ('search.html', ".//meta[@name='robots'][@content='noindex']", ''),