Merge commit '799385f5558a888d1a143bf703d06b66d6717fe4'

CHANGES

@@ -91,6 +91,9 @@ Features added
 * #10125: extlinks: Improve suggestion message for a reference having title
 * #9494, #9456: html search: Add a config variable
   :confval:`html_show_search_summary` to enable/disable the search summaries
+* #9337: HTML theme, add option ``enable_search_shortcuts`` that enables :kbd:'/' as
+         a Quick search shortcut and :kbd:`Esc` shortcut that
+         removes search highlighting.
 
 Bugs fixed
 ----------

doc/usage/theming.rst

@@ -158,9 +158,18 @@ These themes are:
     dimension string such as '70em' or '50%'. Use 'none' if you don't
     want a width limit. Defaults may depend on the theme (often 800px).
 
-  - **navigation_with_keys** (true or false): Allow navigating to the
-    previous/next page using the keyboard's left and right arrows.  Defaults to
-    ``False``.
+  - **navigation_with_keys** (true or false): Allow navigating
+    with the following keyboard shortcuts:
+
+    - :kbd:`Left arrow`: previous page
+    - :kbd:`Right arrow`: next page
+
+    Defaults to ``False``.
+
+  - **enable_search_shortcuts** (true or false): Allow jumping to the search box
+    with :kbd:`/` and allow removal of search highlighting with :kbd:`Esc`.
+
+    Defaults to ``True``.
 
   - **globaltoc_collapse** (true or false): Only expand subsections
     of the current document in ``globaltoc.html``

sphinx/themes/basic/static/doctools.js

@@ -86,8 +86,7 @@ const Documentation = {
   init: () => {
     Documentation.highlightSearchWords();
     Documentation.initDomainIndexTable();
-    if (DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS)
-      Documentation.initOnKeyListeners();
+    Documentation.initOnKeyListeners();
   },
 
   /**
@@ -173,6 +172,16 @@ const Documentation = {
     window.history.replaceState({}, '', url);
   },
 
+  /**
+   * helper function to focus on search bar
+   */
+  focusSearchBar : () => {
+    document
+      .querySelectorAll("input[name=q]")
+      .first()
+      .focus()
+  },
+
   /**
    * Initialise the domain index toggle buttons
    */
@@ -198,6 +207,11 @@ const Documentation = {
   },
 
   initOnKeyListeners: () => {
+    // only install a listener if it is really needed
+    if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS &&
+        !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS)
+        return;
+
     const blacklistedElements = new Set([
       "TEXTAREA",
       "INPUT",
@@ -206,14 +220,46 @@ const Documentation = {
     ]);
     document.addEventListener("keydown", (event) => {
       if (blacklistedElements.has(document.activeElement.tagName)) return; // bail for input elements
-      if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey)
+      if (event.altKey || event.ctrlKey || event.metaKey)
         return; // bail with special keys
-      if (event.key === "ArrowLeft") {
-        const prevLink = document.querySelector('link[rel="prev"]');
-        if (prevLink && prevLink.href) window.location.href = prevLink.href;
-      } else if (event.key === "ArrowRight") {
-        const nextLink = document.querySelector('link[rel="next"]').href;
-        if (nextLink && nextLink.href) window.location.href = nextLink.href;
+
+      if (!event.shiftKey) {
+        switch (event.key) {
+          case "ArrowLeft":
+            if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS)
+              break;
+
+            const prevLink = document.querySelector('link[rel="prev"]');
+            if (prevLink && prevLink.href) {
+              window.location.href = prevLink.href;
+              return false;
+            }
+            break;
+          case "ArrowRight":
+            if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS)
+              break;
+
+            const nextLink = document.querySelector('link[rel="next"]').href;
+            if (nextLink && nextLink.href) {
+              window.location.href = nextLink.href;
+              return false;
+            }
+            break;
+          case "Escape":
+            if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS)
+              break;
+            Documentation.hideSearchWords();
+            return false;
+        }
+      }
+
+      // some keyboard layouts may need Shift to get /
+      switch (event.key) {
+        case '/':
+          if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS)
+            break;
+          Documentation.focusSearchBar();
+          return false;
       }
     });
   },

sphinx/themes/basic/static/documentation_options.js_t

@@ -9,5 +9,6 @@ var DOCUMENTATION_OPTIONS = {
     HAS_SOURCE: {{ has_source|lower }},
     SOURCELINK_SUFFIX: '{{ sourcelink_suffix }}',
     NAVIGATION_WITH_KEYS: {{ 'true' if theme_navigation_with_keys|tobool else 'false'}},
-    SHOW_SEARCH_SUMMARY: {{ 'true' if show_search_summary else 'false' }}
+    SHOW_SEARCH_SUMMARY: {{ 'true' if show_search_summary else 'false' }},
+    ENABLE_SEARCH_SHORTCUTS: {{ 'true' if enable_search_shortcuts|tobool else 'true'}},
 };

sphinx/themes/basic/theme.conf

@@ -10,6 +10,7 @@ sidebarwidth = 230
 body_min_width = 450
 body_max_width = 800
 navigation_with_keys = False
+enable_search_shortcuts = True
 globaltoc_collapse = true
 globaltoc_includehidden = false
 globaltoc_maxdepth =