| 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 |
} |