[3.13] GH-121970: Improve the glossary preview in HTML search (GH-121991) (#122015)

GH-121970: Improve the glossary preview in HTML search (GH-121991)
(cherry picked from commit adf0b94d1c)

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

Doc/tools/extensions/glossary_search.py

@@ -1,63 +1,59 @@
-# -*- coding: utf-8 -*-
-"""
-    glossary_search.py
-    ~~~~~~~~~~~~~~~~
+"""Feature search results for glossary items prominently."""
 
-    Feature search results for glossary items prominently.
+from __future__ import annotations
 
-    :license: Python license.
-"""
 import json
-import os.path
-from docutils.nodes import definition_list_item
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from docutils import nodes
 from sphinx.addnodes import glossary
 from sphinx.util import logging
 
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+    from sphinx.util.typing import ExtensionMetadata
 
 logger = logging.getLogger(__name__)
-STATIC_DIR = '_static'
-JSON = 'glossary.json'
 
 
-def process_glossary_nodes(app, doctree, fromdocname):
+def process_glossary_nodes(app: Sphinx, doctree: nodes.document, _docname: str) -> None:
     if app.builder.format != 'html' or app.builder.embedded:
         return
 
-    terms = {}
+    if hasattr(app.env, 'glossary_terms'):
+        terms = app.env.glossary_terms
+    else:
+        terms = app.env.glossary_terms = {}
 
     for node in doctree.findall(glossary):
-        for glossary_item in node.findall(definition_list_item):
-            term = glossary_item[0].astext().lower()
-            definition = glossary_item[1]
+        for glossary_item in node.findall(nodes.definition_list_item):
+            term = glossary_item[0].astext()
+            definition = glossary_item[-1]
 
             rendered = app.builder.render_partial(definition)
-            terms[term] = {
-                'title': glossary_item[0].astext(),
+            terms[term.lower()] = {
+                'title': term,
                 'body': rendered['html_body']
             }
 
-    if hasattr(app.env, 'glossary_terms'):
-        app.env.glossary_terms.update(terms)
-    else:
-        app.env.glossary_terms = terms
 
-def on_build_finish(app, exc):
-    if not hasattr(app.env, 'glossary_terms'):
-        return
-    if not app.env.glossary_terms:
+def write_glossary_json(app: Sphinx, _exc: Exception) -> None:
+    if not getattr(app.env, 'glossary_terms', None):
         return
 
-    logger.info(f'Writing {JSON}', color='green')
-
-    dest_dir = os.path.join(app.outdir, STATIC_DIR)
-    os.makedirs(dest_dir, exist_ok=True)
-
-    with open(os.path.join(dest_dir, JSON), 'w') as f:
-        json.dump(app.env.glossary_terms, f)
+    logger.info(f'Writing glossary.json', color='green')
+    dest = Path(app.outdir, '_static', 'glossary.json')
+    dest.parent.mkdir(exist_ok=True)
+    dest.write_text(json.dumps(app.env.glossary_terms), encoding='utf-8')
 
 
-def setup(app):
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.connect('doctree-resolved', process_glossary_nodes)
-    app.connect('build-finished', on_build_finish)
+    app.connect('build-finished', write_glossary_json)
 
-    return {'version': '0.1', 'parallel_read_safe': True}
+    return {
+        'version': '1.0',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }