HTML search: adjustments to type-dependent CSS classnames and defaults (#12815)

Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

doc/_themes/sphinx13/static/sphinx13.css

@@ -702,17 +702,19 @@ ul.search {
 }
 ul.search li {
     padding: 5px 0 5px 10px;
-    list-style-type: "\25A1";  /* Unicode: White Square */
 }
-ul.search li.context-index {
+
+/* note: these rules apply to search results from the built-in Sphinx HTML/JS search engine
+   and only take effect in dev builds. The released docs use the ReadTheDocs search engine and are not affected. */
+ul.search li.kind-index {
     list-style-type: "\1F4D1";  /* Unicode: Bookmark Tabs */
 }
-ul.search li.context-object {
+ul.search li.kind-object {
     list-style-type: "\1F4E6";  /* Unicode: Package */
 }
-ul.search li.context-title {
+ul.search li.kind-title {
     list-style-type: "\1F4C4";  /* Unicode: Page Facing Up */
 }
-ul.search li.context-text {
+ul.search li.kind-text {
     list-style-type: "\1F4C4";  /* Unicode: Page Facing Up */
 }

doc/development/html_themes/index.rst

@@ -238,16 +238,25 @@ Styling search result entries by category
 
 .. versionadded:: 8.0
 
+.. note::
+
+    The CSS classes named below are generated by Sphinx's standalone search
+    code.  If you are using a third-party search provider, such as
+    ReadTheDocs_, to provide search results, then the theming options available
+    may vary.
+
+.. _ReadTheDocs: https://docs.readthedocs.io/
+
 The search result items have classes indicating the context in which the
 search term was found. You can use the CSS selectors:
 
-- ``ul.search li.context-index``:
+- ``ul.search li.kind-index``:
   For results in an index, such as the glossary
-- ``ul.search li.context-object``:
+- ``ul.search li.kind-object``:
   For results in source code, like Python function definitions
-- ``ul.search li.context-title``:
+- ``ul.search li.kind-title``:
   For results found in section headings
-- ``ul.search li.context-text``:
+- ``ul.search li.kind-text``:
   For results found anywhere else in the documentation text
 
 As a base for inheritance by other themes, the ``basic`` theme is
@@ -265,16 +274,16 @@ search result list:
         padding: 5px 0 5px 10px;
         list-style-type: "\25A1";  /* Unicode: White Square */
     }
-    ul.search li.context-index {
+    ul.search li.kind-index {
         list-style-type: "\1F4D1";  /* Unicode: Bookmark Tabs */
     }
-    ul.search li.context-object {
+    ul.search li.kind-object {
         list-style-type: "\1F4E6";  /* Unicode: Package */
     }
-    ul.search li.context-title {
+    ul.search li.kind-title {
         list-style-type: "\1F4C4";  /* Unicode: Page Facing Up */
     }
-    ul.search li.context-text {
+    ul.search li.kind-text {
         list-style-type: "\1F4C4";  /* Unicode: Page Facing Up */
     }
 

sphinx/themes/basic/static/searchtools.js

@@ -20,7 +20,7 @@ if (typeof Scorer === "undefined") {
     // and returns the new score.
     /*
     score: result => {
-      const [docname, title, anchor, descr, score, filename, context] = result
+      const [docname, title, anchor, descr, score, filename, kind] = result
       return score
     },
     */
@@ -48,7 +48,7 @@ if (typeof Scorer === "undefined") {
 }
 
 // Global search result kind enum, used by themes to style search results.
-class SearchResultContext {
+class SearchResultKind {
     static get index() { return  "index"; }
     static get object() { return "object"; }
     static get text() { return "text"; }
@@ -72,13 +72,13 @@ const _displayItem = (item, searchTerms, highlightTerms) => {
   const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY;
   const contentRoot = document.documentElement.dataset.content_root;
 
-  const [docName, title, anchor, descr, score, _filename, context] = item;
+  const [docName, title, anchor, descr, score, _filename, kind] = item;
 
   let listItem = document.createElement("li");
   // Add a class representing the item's type:
   // can be used by a theme's CSS selector for styling
-  // See SearchResultContext for the class names.
-  listItem.classList.add(`context-${context}`);
+  // See SearchResultKind for the class names.
+  listItem.classList.add(`kind-${kind}`);
   let requestUrl;
   let linkUrl;
   if (docBuilder === "dirhtml") {
@@ -152,7 +152,7 @@ const _displayNextItem = (
   else _finishSearch(resultCount);
 };
 // Helper function used by query() to order search results.
-// Each input is an array of [docname, title, anchor, descr, score, filename, context].
+// Each input is an array of [docname, title, anchor, descr, score, filename, kind].
 // Order the results by score (in opposite order of appearance, since the
 // `_displayNextItem` function uses pop() to retrieve items) and then alphabetically.
 const _orderResultsByScoreThenName = (a, b) => {
@@ -333,7 +333,7 @@ const Search = {
     const indexEntries = Search._index.indexentries;
 
     // Collect multiple result groups to be sorted separately and then ordered.
-    // Each is an array of [docname, title, anchor, descr, score, filename, context].
+    // Each is an array of [docname, title, anchor, descr, score, filename, kind].
     const normalResults = [];
     const nonMainIndexResults = [];
 
@@ -352,7 +352,7 @@ const Search = {
             null,
             score + boost,
             filenames[file],
-            SearchResultContext.title,
+            SearchResultKind.title,
           ]);
         }
       }
@@ -370,7 +370,7 @@ const Search = {
             null,
             score,
             filenames[file],
-            SearchResultContext.index,
+            SearchResultKind.index,
           ];
           if (isMain) {
             normalResults.push(result);
@@ -492,7 +492,7 @@ const Search = {
         descr,
         score,
         filenames[match[0]],
-        SearchResultContext.object,
+        SearchResultKind.object,
       ]);
     };
     Object.keys(objects).forEach((prefix) =>
@@ -603,7 +603,7 @@ const Search = {
         null,
         score,
         filenames[file],
-        SearchResultContext.text,
+        SearchResultKind.text,
       ]);
     }
     return results;