Debian Codegraph @

Doc/tools/extensions/glossary_search.py

raw
1 """Feature search results for glossary items prominently."""
2
3 from __future__ import annotations
4
5 import json
6 from pathlib import Path
7 from typing import TYPE_CHECKING
8
9 from docutils import nodes
10 from sphinx.addnodes import glossary
11 from sphinx.util import logging
12
13 if TYPE_CHECKING:
14 from sphinx.application import Sphinx
15 from sphinx.util.typing import ExtensionMetadata
16
17 logger = logging.getLogger(__name__)
18
19
20 def process_glossary_nodes(
21 app: Sphinx,
22 doctree: nodes.document,
23 _docname: str,
24 ) -> None:
25 if app.builder.format != 'html' or app.builder.embedded:
26 return
27
28 if hasattr(app.env, 'glossary_terms'):
29 terms = app.env.glossary_terms
30 else:
31 terms = app.env.glossary_terms = {}
32
33 for node in doctree.findall(glossary):
34 for glossary_item in node.findall(nodes.definition_list_item):
35 term = glossary_item[0].astext()
36 definition = glossary_item[-1]
37
38 rendered = app.builder.render_partial(definition)
39 terms[term.lower()] = {
40 'title': term,
41 'body': rendered['fragment'],
42 }
43
44
45 def write_glossary_json(app: Sphinx, _exc: Exception) -> None:
46 if not getattr(app.env, 'glossary_terms', None):
47 return
48
49 logger.info('Writing glossary.json', color='green')
50 dest = Path(app.outdir, '_static', 'glossary.json')
51 dest.parent.mkdir(exist_ok=True)
52 dest.write_text(json.dumps(app.env.glossary_terms), encoding='utf-8')
53
54
55 def setup(app: Sphinx) -> ExtensionMetadata:
56 app.connect('doctree-resolved', process_glossary_nodes)
57 app.connect('build-finished', write_glossary_json)
58
59 return {
60 'version': '1.0',
61 'parallel_read_safe': True,
62 'parallel_write_safe': True,
63 }