ENH: Add type-dependent class to search result entries

This allows styling different types of results individually.
It's helpful to visually distinguish different content types.

This PR adds `itemType` to the javascript result entries
(one of "title", "index", "object", "text") and adds
them as a class to the <li> item in the result list.
This allows styling via CSS.

The basic theme only contains the mechanism to add the HTML
classes. It does intentionally not do any styling via CSS.
We reserve that freedom to derived themes.

For the internal sphinx13 theme, I've styled with unicode
symbols, which should give a decent look without the need
to ship our own symbols.

CHANGES.rst

@@ -13,6 +13,8 @@ Deprecated
 Features added
 --------------
 
+* #12474: Support type-dependent search result highlighting via CSS
+  Patch by Tim Hoffmann
 * #12456: Add :option:`sphinx-autogen --remove-old` option.
   Patch by Chris Sewell.
 * #12448: Add :option:`sphinx-apidoc --remove-old` option.

doc/_themes/sphinx13/static/sphinx13.css

@@ -526,3 +526,30 @@ then for larger screens align them two per-row. */
     justify-content: center;
     gap: 10px;
 }
+
+/* -- search results -------------------------------------------------------- */
+
+ul.search {
+    padding-left: 30px;
+}
+
+ul.search li {
+    padding: 5px 0 5px 10px;
+    list-style: initial;
+}
+
+ul.search li.index {
+    list-style: "\1F4D1";  /* Unicode: Bookmark Tabs */
+}
+
+ul.search li.object {
+    list-style: "\1F4E6";  /* Unicode: Package */
+}
+
+ul.search li.title {
+    list-style: "\1F4C4";  /* Unicode: Page Facing Up */
+}
+
+ul.search li.text {
+    list-style: "\1F4C4";  /* Unicode: Page Facing Up */
+}

sphinx/themes/basic/static/basic.css_t

@@ -115,15 +115,11 @@ img {
 /* -- search page ----------------------------------------------------------- */
 
 ul.search {
-    margin: 10px 0 0 20px;
-    padding: 0;
+    margin-top: 10px;
 }
 
 ul.search li {
-    padding: 5px 0 5px 20px;
-    background-image: url(file.png);
-    background-repeat: no-repeat;
-    background-position: 0 7px;
+    padding: 5px 0;
 }
 
 ul.search li a {

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] = result
+      const [docname, title, anchor, descr, score, filename, resultType] = result
       return score
     },
     */
@@ -47,6 +47,13 @@ if (typeof Scorer === "undefined") {
   };
 }
 
+const SearchResultType = {
+  index: "index",
+  object: "object",
+  text: "text",
+  title: "title",
+}
+
 const _removeChildren = (element) => {
   while (element && element.lastChild) element.removeChild(element.lastChild);
 };
@@ -64,9 +71,10 @@ 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] = item;
+  const [docName, title, anchor, descr, score, _filename, resultType] = item;
 
   let listItem = document.createElement("li");
+  listItem.classList.add(resultType)
   let requestUrl;
   let linkUrl;
   if (docBuilder === "dirhtml") {
@@ -138,7 +146,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].
+// Each input is an array of [docname, title, anchor, descr, score, filename, resultType].
 // 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) => {
@@ -248,6 +256,7 @@ const Search = {
     searchSummary.classList.add("search-summary");
     searchSummary.innerText = "";
     const searchList = document.createElement("ul");
+    searchList.setAttribute("role", "list")
     searchList.classList.add("search");
 
     const out = document.getElementById("search-results");
@@ -318,7 +327,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].
+    // Each is an array of [docname, title, anchor, descr, score, filename, resultType].
     const normalResults = [];
     const nonMainIndexResults = [];
 
@@ -336,6 +345,7 @@ const Search = {
             null,
             score,
             filenames[file],
+            SearchResultType.title,
           ]);
         }
       }
@@ -353,6 +363,7 @@ const Search = {
             null,
             score,
             filenames[file],
+            SearchResultType.index,
           ];
           if (isMain) {
             normalResults.push(result);
@@ -474,6 +485,7 @@ const Search = {
         descr,
         score,
         filenames[match[0]],
+        SearchResultType.object,
       ]);
     };
     Object.keys(objects).forEach((prefix) =>
@@ -584,6 +596,7 @@ const Search = {
         null,
         score,
         filenames[file],
+        SearchResultType.text,
       ]);
     }
     return results;

tests/js/searchtools.js

@@ -22,7 +22,8 @@ describe('Basic html theme search', function() {
         "",
         null,
         5,
-        "index.rst"
+        "index.rst",
+        "text"
       ]];
       expect(Search.performTermsSearch(searchterms, excluded, terms, titleterms)).toEqual(hits);
     });
@@ -39,7 +40,9 @@ describe('Basic html theme search', function() {
         '',
         null,
         15,
-        'index.rst']];
+        'index.rst',
+        'text'
+      ]];
       expect(Search.performTermsSearch(searchterms, excluded, terms, titleterms)).toEqual(hits);
     });
 
@@ -56,7 +59,8 @@ describe('Basic html theme search', function() {
         "",
         null,
         7,
-        "index.rst"
+        "index.rst",
+        "text"
       ]];
       expect(Search.performTermsSearch(searchterms, excluded, terms, titleterms)).toEqual(hits);
     });
@@ -78,15 +82,17 @@ describe('Basic html theme search', function() {
           '',
           null,
           15,
-          'index.rst'
+          'index.rst',
+          'text'
         ],
         [
           'index',
           'Main Page',
           '#main-page',
           null,
           100,
-          'index.rst'
+          'index.rst',
+          'title'
         ]
       ];
       expect(Search._performSearch(...searchParameters)).toEqual(hits);