Skip to content

GH-121970: Improve the glossary preview in HTML search #121991

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AA-Turner merged 6 commits into from
Jul 19, 2024
Merged

GH-121970: Improve the glossary preview in HTML search #121991

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
15a7483
Move glossary_search.js to its own file
AA-Turner Jul 18, 2024
3114261
Update glossary_search.js
AA-Turner Jul 18, 2024
006d635
Don't create HTML via JS
AA-Turner Jul 18, 2024
d6fa0be
Update glossary_search.py
AA-Turner Jul 18, 2024
df586fb
Class -> ID
AA-Turner Jul 18, 2024
4ad98c9
Merge branch 'main' into docs/glossary_search
hugovk Jul 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Update glossary_search.py
  • Loading branch information
@AA-Turner
AA-Turner committed Jul 18, 2024
commit d6fa0bef58320af62c5e16301d545b76262554ee
68 changes: 32 additions & 36 deletions Doc/tools/extensions/glossary_search.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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,
}