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

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 -*-
+"""Feature search results for glossary items prominently."""
-"""
-    glossary_search.py
-    ~~~~~~~~~~~~~~~~
 
-    Feature search results for glossary items prominently.
+from __future__ import annotations
 
-    :license: Python license.
-"""
 import json
-import os.path
+from pathlib import Path
-from docutils.nodes import definition_list_item
+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):
+        for glossary_item in node.findall(nodes.definition_list_item):
-            term = glossary_item[0].astext().lower()
+            term = glossary_item[0].astext()
-            definition = glossary_item[1]
+            definition = glossary_item[-1]
 
             rendered = app.builder.render_partial(definition)
-            terms[term] = {
+            terms[term.lower()] = {
-                'title': glossary_item[0].astext(),
+                '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):
+def write_glossary_json(app: Sphinx, _exc: Exception) -> None:
-    if not hasattr(app.env, 'glossary_terms'):
+    if not getattr(app.env, 'glossary_terms', None):
-        return
-    if not app.env.glossary_terms:
         return
 
-    logger.info(f'Writing {JSON}', color='green')
+    logger.info(f'Writing glossary.json', color='green')
-
+    dest = Path(app.outdir, '_static', 'glossary.json')
-    dest_dir = os.path.join(app.outdir, STATIC_DIR)
+    dest.parent.mkdir(exist_ok=True)
-    os.makedirs(dest_dir, exist_ok=True)
+    dest.write_text(json.dumps(app.env.glossary_terms), encoding='utf-8')
-
-    with open(os.path.join(dest_dir, JSON), 'w') as f:
-        json.dump(app.env.glossary_terms, f)
 
 
-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,
+    }

Doc/tools/static/glossary_search.js

@@ -0,0 +1,47 @@
+"use strict";
+
+const GLOSSARY_PAGE = "glossary.html";
+
+const glossary_search = async () => {
+  const response = await fetch("_static/glossary.json");
+  if (!response.ok) {
+    throw new Error("Failed to fetch glossary.json");
+  }
+  const glossary = await response.json();
+
+  const params = new URLSearchParams(document.location.search).get("q");
+  if (!params) {
+    return;
+  }
+
+  const searchParam = params.toLowerCase();
+  const glossaryItem = glossary[searchParam];
+  if (!glossaryItem) {
+    return;
+  }
+
+  // set up the title text with a link to the glossary page
+  const glossaryTitle = document.getElementById("glossary-title");
+  glossaryTitle.textContent = "Glossary: " + glossaryItem.title;
+  const linkTarget = searchParam.replace(/ /g, "-");
+  glossaryTitle.href = GLOSSARY_PAGE + "#term-" + linkTarget;
+
+  // rewrite any anchor links (to other glossary terms)
+  // to have a full reference to the glossary page
+  const glossaryBody = document.getElementById("glossary-body");
+  glossaryBody.innerHTML = glossaryItem.body;
+  const anchorLinks = glossaryBody.querySelectorAll('a[href^="#"]');
+  anchorLinks.forEach(function (link) {
+    const currentUrl = link.getAttribute("href");
+    link.href = GLOSSARY_PAGE + currentUrl;
+  });
+
+  const glossaryResult = document.getElementById("glossary-result");
+  glossaryResult.style.display = "";
+};
+
+if (document.readyState !== "loading") {
+  glossary_search().catch(console.error);
+} else {
+  document.addEventListener("DOMContentLoaded", glossary_search);
+}

Doc/tools/templates/search.html

@@ -2,61 +2,16 @@
 {% block extrahead %}
     {{ super() }}
     <meta name="robots" content="noindex">
-    <script type="text/javascript">
+    <script type="text/javascript" src="{{ pathto('_static/glossary_search.js', resource=True) }}"></script>
-        const GLOSSARY_PAGE = 'glossary.html';
+{% endblock %}
-
+{% block searchresults %}
-        document.addEventListener('DOMContentLoaded', function() {
+<div id="search-results">
-          fetch('_static/glossary.json')
+  {# For glossary_search.js #}
-            .then(function(response) {
+  <div style="display: none;" class="admonition seealso" id="glossary-result">
-              if (response.ok) {
+    <p class="topic-title">
-                return response.json();
+    <a id="glossary-title" href="#"></a>
-              } else {
+    </p>
-                throw new Error('Failed to fetch glossary.json');
+  <div id="glossary-body"></div>
-              }
+</div>
-            })
+</div>
-            .then(function(glossary) {
-              const RESULT_TEMPLATE = '<div style="display: none" class="admonition seealso" id="glossary-result">' +
-                                      '  <p class="topic-title">' +
-                                      '    <a class="glossary-title" href="#"></a>' +
-                                      '  </p>' +
-                                      '  <div class="glossary-body"></div>' +
-                                      '</div>';
-              let searchResults = document.getElementById('search-results');
-              searchResults.insertAdjacentHTML('afterbegin', RESULT_TEMPLATE);
-
-              const params = new URLSearchParams(document.location.search).get("q");
-              if (params) {
-                const searchParam = params.toLowerCase();
-                const glossaryItem = glossary[searchParam];
-                if (glossaryItem) {
-                  let resultDiv = document.getElementById('glossary-result');
-
-                  // set up the title text with a link to the glossary page
-                  let glossaryTitle = resultDiv.querySelector('.glossary-title');
-                  glossaryTitle.textContent = 'Glossary: ' + glossaryItem.title;
-                  const linkTarget = searchParam.replace(/ /g, '-');
-                  glossaryTitle.href = GLOSSARY_PAGE + '#term-' + linkTarget;
-
-                  // rewrite any anchor links (to other glossary terms)
-                  // to have a full reference to the glossary page
-                  let body = document.createElement('div');
-                  body.innerHTML = glossaryItem.body;
-                  const anchorLinks = body.querySelectorAll('a[href^="#"]');
-                  anchorLinks.forEach(function(link) {
-                    const currentUrl = link.getAttribute('href');
-                    link.href = GLOSSARY_PAGE + currentUrl;
-                  });
-                  resultDiv.querySelector('.glossary-body').appendChild(body);
-
-                  resultDiv.style.display = '';
-                } else {
-                  document.getElementById('glossary-result').style.display = 'none';
-                }
-              }
-            })
-            .catch(function(error) {
-              console.error(error);
-            });
-        });
-    </script>
 {% endblock %}