diff --git a/CHANGES b/CHANGES index 6ad4f4b1a..f52612340 100644 --- a/CHANGES +++ b/CHANGES @@ -88,6 +88,9 @@ Deprecated Features added -------------- +* #9494, #9456: html search: Add a config variable + :confval:`html_show_search_summary` to enable/disable the search summaries + Bugs fixed ---------- diff --git a/EXAMPLES b/EXAMPLES index 1f554dc2e..da41e20e2 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -246,7 +246,7 @@ Documentation using sphinx_rtd_theme * `Nextflow `__ * `nghttp2 `__ * `NICOS `__ (customized) -* `OpenFAST `__ +* `OpenFAST `__ * `Panda3D `__ (customized) * `Pelican `__ * `picamera `__ @@ -454,7 +454,7 @@ Books produced using Sphinx * `"Theoretical Physics Reference" `__ * `"The Varnish Book" `__ -These produced using Sphinx +Theses produced using Sphinx ---------------------------- * `"A Web-Based System for Comparative Analysis of OpenStreetMap Data by the Use diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index b5bd02e4f..685273fe7 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -1351,6 +1351,13 @@ that use Sphinx's HTMLWriter class. .. versionadded:: 1.0 +.. confval:: html_show_search_summary + + If true, the text around the keyword is shown as summary of each search result. + Default is ``True``. + + .. versionadded:: 4.5 + .. confval:: html_show_sphinx If true, "Created using Sphinx" is shown in the HTML footer. Default is diff --git a/sphinx/builders/html/__init__.py b/sphinx/builders/html/__init__.py index da3b86b34..cc8e676e2 100644 --- a/sphinx/builders/html/__init__.py +++ b/sphinx/builders/html/__init__.py @@ -510,6 +510,7 @@ class StandaloneHTMLBuilder(Builder): 'docstitle': self.config.html_title, 'shorttitle': self.config.html_short_title, 'show_copyright': self.config.html_show_copyright, + 'show_search_summary': self.config.html_show_search_summary, 'show_sphinx': self.config.html_show_sphinx, 'has_source': self.config.html_copy_source, 'show_source': self.config.html_show_sourcelink, @@ -1340,6 +1341,7 @@ def setup(app: Sphinx) -> Dict[str, Any]: app.add_config_value('html_file_suffix', None, 'html', [str]) app.add_config_value('html_link_suffix', None, 'html', [str]) app.add_config_value('html_show_copyright', True, 'html') + app.add_config_value('html_show_search_summary', True, 'html') app.add_config_value('html_show_sphinx', True, 'html') app.add_config_value('html_context', {}, 'html') app.add_config_value('html_output_encoding', 'utf-8', 'html') diff --git a/sphinx/themes/basic/static/documentation_options.js_t b/sphinx/themes/basic/static/documentation_options.js_t index 8afaac2f8..5f4cca454 100644 --- a/sphinx/themes/basic/static/documentation_options.js_t +++ b/sphinx/themes/basic/static/documentation_options.js_t @@ -8,5 +8,6 @@ var DOCUMENTATION_OPTIONS = { LINK_SUFFIX: '{{ link_suffix }}', HAS_SOURCE: {{ has_source|lower }}, SOURCELINK_SUFFIX: '{{ sourcelink_suffix }}', - NAVIGATION_WITH_KEYS: {{ 'true' if theme_navigation_with_keys|tobool else 'false'}} + NAVIGATION_WITH_KEYS: {{ 'true' if theme_navigation_with_keys|tobool else 'false'}}, + SHOW_SEARCH_SUMMARY: {{ 'true' if show_search_summary else 'false' }} }; diff --git a/sphinx/themes/basic/static/searchtools.js b/sphinx/themes/basic/static/searchtools.js index 943507508..cba0817ce 100644 --- a/sphinx/themes/basic/static/searchtools.js +++ b/sphinx/themes/basic/static/searchtools.js @@ -62,7 +62,7 @@ const _displayItem = (item, highlightTerms, searchTerms) => { const docUrlRoot = DOCUMENTATION_OPTIONS.URL_ROOT; const docFileSuffix = DOCUMENTATION_OPTIONS.FILE_SUFFIX; const docLinkSuffix = DOCUMENTATION_OPTIONS.LINK_SUFFIX; - const docHasSource = DOCUMENTATION_OPTIONS.HAS_SOURCE; + const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY; const [docName, title, anchor, descr] = item; @@ -90,7 +90,7 @@ const _displayItem = (item, highlightTerms, searchTerms) => { if (descr) listItem.appendChild(document.createElement("span")).innerText = " (" + descr + ")"; - else if (docHasSource) + else if (showSearchSummary) fetch(requestUrl) .then((responseData) => responseData.text()) .then((data) => {