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.
sphinx-doc · Jun 30, 2024 · b4affb1 · b4affb1
1 parent f85f50e
commit b4affb1
Show file tree

Hide file tree

Showing 4 changed files with 58 additions and 15 deletions.
diff --git a/doc/_themes/sphinx13/static/sphinx13.css b/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 */
+}
diff --git a/sphinx/themes/basic/static/basic.css_t b/sphinx/themes/basic/static/basic.css_t
@@ -115,16 +115,13 @@ img {
 /* -- search page ----------------------------------------------------------- */
 
 ul.search {
-    margin: 10px 0 0 20px;
+    margin: 10px 0;
     padding: 0;
 }
 
 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 {
     font-weight: bold;

diff --git a/sphinx/themes/basic/static/searchtools.js b/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;

diff --git a/tests/js/searchtools.js b/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);