bpo-34398: Allow glossary results to show up on search page (GH-8773)

This commit is contained in:
Ammar Askar 2020-12-18 14:00:51 -05:00 committed by GitHub
parent d75f6f78e6
commit 8c5d0347ef
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 108 additions and 2 deletions

View File

@ -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:

View File

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

View File

@ -0,0 +1,48 @@
{% extends "!search.html" %}
{% block extrahead %}
{{ super() }}
<script type="text/javascript">
var GLOSSARY_PAGE = 'glossary.html';
jQuery(function() {
$.getJSON("_static/glossary.json", function(glossary) {
var 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>';
$("#search-results").prepend(RESULT_TEMPLATE);
var params = $.getQueryParameters();
if (params.q) {
var search_param = params.q[0].toLowerCase();
var glossary_item = glossary[search_param];
if (glossary_item) {
var resultDiv = $("#glossary-result");
// set up the title text with a link to the glossary page
resultDiv.find(".glossary-title").text('Glossary: ' + glossary_item.title);
var link_target = search_param.replace(/ /g, '-');
resultDiv.find(".glossary-title").attr(
'href', GLOSSARY_PAGE + '#term-' + link_target
);
// rewrite any anchor links (to other glossary terms)
// to have a full reference to the glossary page
var body = $(glossary_item.body).children();
body.find("a[href^='#']").each(function() {
var current_url = $(this).attr('href');
$(this).attr('href', GLOSSARY_PAGE + current_url);
});
resultDiv.find(".glossary-body").html(body);
resultDiv.show();
} else {
$("#glossary-result").hide('');
}
}
});
});
</script>
{% endblock %}

View File

@ -0,0 +1,2 @@
Prominently feature listings from the glossary in documentation search
results. Patch by Ammar Askar.