From 92f024e2bf09d2d418c3c4a58e85fc788abf289f Mon Sep 17 00:00:00 2001 From: James Addison <55152140+jayaddison@users.noreply.github.com> Date: Wed, 18 Sep 2024 02:40:20 +0000 Subject: [PATCH] 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 | 12 ++++++----- doc/development/html_themes/index.rst | 25 +++++++++++++++-------- sphinx/themes/basic/static/searchtools.js | 22 ++++++++++---------- 3 files changed, 35 insertions(+), 24 deletions(-) diff --git a/doc/_themes/sphinx13/static/sphinx13.css b/doc/_themes/sphinx13/static/sphinx13.css index b0501d34394..4142c3d6302 100644 --- a/doc/_themes/sphinx13/static/sphinx13.css +++ b/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 */ } diff --git a/doc/development/html_themes/index.rst b/doc/development/html_themes/index.rst index 3cfb40dc3a7..bc75beb7ba7 100644 --- a/doc/development/html_themes/index.rst +++ b/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 */ } diff --git a/sphinx/themes/basic/static/searchtools.js b/sphinx/themes/basic/static/searchtools.js index 2b058e13bec..e89bfc3aebf 100644 --- 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, 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;