Merge pull request #10108 from tk0miya/9456_html_show_search_summary

Close #9456: html search: Add a config variable; html_show_search_summary

Author: tk0miya

CHANGES

@@ -13,6 +13,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
 ----------
 

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

sphinx/builders/html/__init__.py

@@ -509,6 +509,7 @@ def prepare_writing(self, docnames: Set[str]) -> None:
             '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')

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' }}
 };

sphinx/themes/basic/static/searchtools.js

@@ -276,7 +276,7 @@ var Search = {
           setTimeout(function() {
             displayNextItem();
           }, 5);
-        } else if (DOCUMENTATION_OPTIONS.HAS_SOURCE) {
+        } else if (DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY) {
           $.ajax({url: requestUrl,
                   dataType: "text",
                   complete: function(jqxhr, textstatus) {
@@ -293,7 +293,7 @@ var Search = {
                     }, 5);
                   }});
         } else {
-          // no source available, just display title
+          // just display title
           Search.output.append(listItem);
           setTimeout(function() {
             displayNextItem();