Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions doc/_themes/sphinx13/static/sphinx13.css
Original file line number Diff line number Diff line change
Expand Up @@ -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 */
}
25 changes: 17 additions & 8 deletions doc/development/html_themes/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 */
}

Expand Down
22 changes: 11 additions & 11 deletions sphinx/themes/basic/static/searchtools.js
Original file line number Diff line number Diff line change
Expand Up @@ -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
},
*/
Expand Down Expand Up @@ -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"; }
Expand All @@ -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") {
Expand Down Expand Up @@ -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) => {
Expand Down Expand Up @@ -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 = [];

Expand All @@ -352,7 +352,7 @@ const Search = {
null,
score + boost,
filenames[file],
SearchResultContext.title,
SearchResultKind.title,
]);
}
}
Expand All @@ -370,7 +370,7 @@ const Search = {
null,
score,
filenames[file],
SearchResultContext.index,
SearchResultKind.index,
];
if (isMain) {
normalResults.push(result);
Expand Down Expand Up @@ -492,7 +492,7 @@ const Search = {
descr,
score,
filenames[match[0]],
SearchResultContext.object,
SearchResultKind.object,
]);
};
Object.keys(objects).forEach((prefix) =>
Expand Down Expand Up @@ -603,7 +603,7 @@ const Search = {
null,
score,
filenames[file],
SearchResultContext.text,
SearchResultKind.text,
]);
}
return results;
Expand Down