diff --git a/Doc/conf.py b/Doc/conf.py index 079d17717f3..6b88c23a444 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -15,8 +15,7 @@ sys.path.append(os.path.abspath('includes')) extensions = ['sphinx.ext.coverage', 'sphinx.ext.doctest', 'pyspecific', 'c_annotations', 'escape4chm', - 'asdl_highlight', 'peg_highlight'] - + 'asdl_highlight', 'peg_highlight', 'glossary_search'] doctest_global_setup = ''' try: diff --git a/Doc/tools/extensions/glossary_search.py b/Doc/tools/extensions/glossary_search.py new file mode 100644 index 00000000000..34d227d6702 --- /dev/null +++ b/Doc/tools/extensions/glossary_search.py @@ -0,0 +1,57 @@ +# -*- coding: utf-8 -*- +""" + glossary_search.py + ~~~~~~~~~~~~~~~~ + + Feature search results for glossary items prominently. + + :license: Python license. +""" +from os import path +from sphinx.addnodes import glossary +from sphinx.util import logging +from docutils.nodes import definition_list_item +import json + + +logger = logging.getLogger(__name__) + + +def process_glossary_nodes(app, doctree, fromdocname): + if app.builder.format != 'html': + return + + terms = {} + + for node in doctree.traverse(glossary): + for glossary_item in node.traverse(definition_list_item): + term = glossary_item[0].astext().lower() + definition = glossary_item[1] + + rendered = app.builder.render_partial(definition) + terms[term] = { + 'title': glossary_item[0].astext(), + '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: + return + + logger.info('Writing glossary.json', color='green') + with open(path.join(app.outdir, '_static', 'glossary.json'), 'w') as f: + json.dump(app.env.glossary_terms, f) + + +def setup(app): + app.connect('doctree-resolved', process_glossary_nodes) + app.connect('build-finished', on_build_finish) + + return {'version': '0.1', 'parallel_read_safe': True} diff --git a/Doc/tools/templates/search.html b/Doc/tools/templates/search.html new file mode 100644 index 00000000000..cf20c2e1d4f --- /dev/null +++ b/Doc/tools/templates/search.html @@ -0,0 +1,48 @@ +{% extends "!search.html" %} +{% block extrahead %} + {{ super() }} + +{% endblock %} \ No newline at end of file diff --git a/Misc/NEWS.d/next/Documentation/2019-03-04-18-51-21.bpo-34398.YedUqW.rst b/Misc/NEWS.d/next/Documentation/2019-03-04-18-51-21.bpo-34398.YedUqW.rst new file mode 100644 index 00000000000..4693cecdb7b --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2019-03-04-18-51-21.bpo-34398.YedUqW.rst @@ -0,0 +1,2 @@ +Prominently feature listings from the glossary in documentation search +results. Patch by Ammar Askar.