Skip to content

Commit 8c5d034

Browse files
authored
bpo-34398: Allow glossary results to show up on search page (GH-8773)
1 parent d75f6f7 commit 8c5d034

File tree

4 files changed

+108
-2
lines changed

4 files changed

+108
-2
lines changed

Doc/conf.py

+1-2
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,7 @@
1515

1616
extensions = ['sphinx.ext.coverage', 'sphinx.ext.doctest',
1717
'pyspecific', 'c_annotations', 'escape4chm',
18-
'asdl_highlight', 'peg_highlight']
19-
18+
'asdl_highlight', 'peg_highlight', 'glossary_search']
2019

2120
doctest_global_setup = '''
2221
try:
+57
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# -*- coding: utf-8 -*-
2+
"""
3+
glossary_search.py
4+
~~~~~~~~~~~~~~~~
5+
6+
Feature search results for glossary items prominently.
7+
8+
:license: Python license.
9+
"""
10+
from os import path
11+
from sphinx.addnodes import glossary
12+
from sphinx.util import logging
13+
from docutils.nodes import definition_list_item
14+
import json
15+
16+
17+
logger = logging.getLogger(__name__)
18+
19+
20+
def process_glossary_nodes(app, doctree, fromdocname):
21+
if app.builder.format != 'html':
22+
return
23+
24+
terms = {}
25+
26+
for node in doctree.traverse(glossary):
27+
for glossary_item in node.traverse(definition_list_item):
28+
term = glossary_item[0].astext().lower()
29+
definition = glossary_item[1]
30+
31+
rendered = app.builder.render_partial(definition)
32+
terms[term] = {
33+
'title': glossary_item[0].astext(),
34+
'body': rendered['html_body']
35+
}
36+
37+
if hasattr(app.env, 'glossary_terms'):
38+
app.env.glossary_terms.update(terms)
39+
else:
40+
app.env.glossary_terms = terms
41+
42+
def on_build_finish(app, exc):
43+
if not hasattr(app.env, 'glossary_terms'):
44+
return
45+
if not app.env.glossary_terms:
46+
return
47+
48+
logger.info('Writing glossary.json', color='green')
49+
with open(path.join(app.outdir, '_static', 'glossary.json'), 'w') as f:
50+
json.dump(app.env.glossary_terms, f)
51+
52+
53+
def setup(app):
54+
app.connect('doctree-resolved', process_glossary_nodes)
55+
app.connect('build-finished', on_build_finish)
56+
57+
return {'version': '0.1', 'parallel_read_safe': True}

Doc/tools/templates/search.html

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
{% extends "!search.html" %}
2+
{% block extrahead %}
3+
{{ super() }}
4+
<script type="text/javascript">
5+
var GLOSSARY_PAGE = 'glossary.html';
6+
7+
jQuery(function() {
8+
$.getJSON("_static/glossary.json", function(glossary) {
9+
var RESULT_TEMPLATE = '<div style="display: none" class="admonition seealso" id="glossary-result">' +
10+
' <p class="topic-title">' +
11+
' <a class="glossary-title" href="#"></a>' +
12+
' </p>' +
13+
' <div class="glossary-body"></div>' +
14+
'</div>';
15+
$("#search-results").prepend(RESULT_TEMPLATE);
16+
17+
var params = $.getQueryParameters();
18+
if (params.q) {
19+
var search_param = params.q[0].toLowerCase();
20+
var glossary_item = glossary[search_param];
21+
if (glossary_item) {
22+
var resultDiv = $("#glossary-result");
23+
24+
// set up the title text with a link to the glossary page
25+
resultDiv.find(".glossary-title").text('Glossary: ' + glossary_item.title);
26+
var link_target = search_param.replace(/ /g, '-');
27+
resultDiv.find(".glossary-title").attr(
28+
'href', GLOSSARY_PAGE + '#term-' + link_target
29+
);
30+
31+
// rewrite any anchor links (to other glossary terms)
32+
// to have a full reference to the glossary page
33+
var body = $(glossary_item.body).children();
34+
body.find("a[href^='#']").each(function() {
35+
var current_url = $(this).attr('href');
36+
$(this).attr('href', GLOSSARY_PAGE + current_url);
37+
});
38+
resultDiv.find(".glossary-body").html(body);
39+
40+
resultDiv.show();
41+
} else {
42+
$("#glossary-result").hide('');
43+
}
44+
}
45+
});
46+
});
47+
</script>
48+
{% endblock %}
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Prominently feature listings from the glossary in documentation search
2+
results. Patch by Ammar Askar.

0 commit comments

Comments
 (0)