update docs [bot]

This commit is contained in:
github-actions 2024-04-24 23:27:19 +00:00
parent 27c055ae05
commit a1edadee6a
13 changed files with 117 additions and 72 deletions

View File

@ -4,7 +4,7 @@
* *
* Sphinx stylesheet -- basic theme. * Sphinx stylesheet -- basic theme.
* *
* :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details. * :license: BSD, see LICENSE for details.
* *
*/ */

View File

@ -4,7 +4,7 @@
* *
* Base JavaScript utilities for all Sphinx HTML documentation. * Base JavaScript utilities for all Sphinx HTML documentation.
* *
* :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details. * :license: BSD, see LICENSE for details.
* *
*/ */

View File

@ -5,7 +5,7 @@
* This script contains the language-specific data used by searchtools.js, * This script contains the language-specific data used by searchtools.js,
* namely the list of stopwords, stemmer, scorer and splitter. * namely the list of stopwords, stemmer, scorer and splitter.
* *
* :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details. * :license: BSD, see LICENSE for details.
* *
*/ */
@ -13,7 +13,7 @@
var stopwords = ["a", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "near", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"]; var stopwords = ["a", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "near", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"];
/* Non-minified version is copied as a separate JS file, is available */ /* Non-minified version is copied as a separate JS file, if available */
/** /**
* Porter Stemmer * Porter Stemmer

View File

@ -4,7 +4,7 @@
* *
* Sphinx JavaScript utilities for the full-text search. * Sphinx JavaScript utilities for the full-text search.
* *
* :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details. * :license: BSD, see LICENSE for details.
* *
*/ */
@ -99,7 +99,7 @@ const _displayItem = (item, searchTerms, highlightTerms) => {
.then((data) => { .then((data) => {
if (data) if (data)
listItem.appendChild( listItem.appendChild(
Search.makeSearchSummary(data, searchTerms) Search.makeSearchSummary(data, searchTerms, anchor)
); );
// highlight search terms in the summary // highlight search terms in the summary
if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js
@ -116,8 +116,8 @@ const _finishSearch = (resultCount) => {
); );
else else
Search.status.innerText = _( Search.status.innerText = _(
`Search finished, found ${resultCount} page(s) matching the search query.` "Search finished, found ${resultCount} page(s) matching the search query."
); ).replace('${resultCount}', resultCount);
}; };
const _displayNextItem = ( const _displayNextItem = (
results, results,
@ -137,6 +137,22 @@ const _displayNextItem = (
// search finished, update title and status message // search finished, update title and status message
else _finishSearch(resultCount); else _finishSearch(resultCount);
}; };
// Helper function used by query() to order search results.
// Each input is an array of [docname, title, anchor, descr, score, filename].
// 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) => {
const leftScore = a[4];
const rightScore = b[4];
if (leftScore === rightScore) {
// same score: sort alphabetically
const leftTitle = a[1].toLowerCase();
const rightTitle = b[1].toLowerCase();
if (leftTitle === rightTitle) return 0;
return leftTitle > rightTitle ? -1 : 1; // inverted is intentional
}
return leftScore > rightScore ? 1 : -1;
};
/** /**
* Default splitQuery function. Can be overridden in ``sphinx.search`` with a * Default splitQuery function. Can be overridden in ``sphinx.search`` with a
@ -160,13 +176,26 @@ const Search = {
_queued_query: null, _queued_query: null,
_pulse_status: -1, _pulse_status: -1,
htmlToText: (htmlString) => { htmlToText: (htmlString, anchor) => {
const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html'); const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html');
htmlElement.querySelectorAll(".headerlink").forEach((el) => { el.remove() }); for (const removalQuery of [".headerlinks", "script", "style"]) {
htmlElement.querySelectorAll(removalQuery).forEach((el) => { el.remove() });
}
if (anchor) {
const anchorContent = htmlElement.querySelector(`[role="main"] ${anchor}`);
if (anchorContent) return anchorContent.textContent;
console.warn(
`Anchored content block not found. Sphinx search tries to obtain it via DOM query '[role=main] ${anchor}'. Check your theme or template.`
);
}
// if anchor not specified or not found, fall back to main content
const docContent = htmlElement.querySelector('[role="main"]'); const docContent = htmlElement.querySelector('[role="main"]');
if (docContent !== undefined) return docContent.textContent; if (docContent) return docContent.textContent;
console.warn( console.warn(
"Content block not found. Sphinx search tries to obtain it via '[role=main]'. Could you check your theme or template." "Content block not found. Sphinx search tries to obtain it via DOM query '[role=main]'. Check your theme or template."
); );
return ""; return "";
}, },
@ -239,16 +268,7 @@ const Search = {
else Search.deferQuery(query); else Search.deferQuery(query);
}, },
/** _parseQuery: (query) => {
* execute search (requires search index to be loaded)
*/
query: (query) => {
const filenames = Search._index.filenames;
const docNames = Search._index.docnames;
const titles = Search._index.titles;
const allTitles = Search._index.alltitles;
const indexEntries = Search._index.indexentries;
// stem the search terms and add them to the correct list // stem the search terms and add them to the correct list
const stemmer = new Stemmer(); const stemmer = new Stemmer();
const searchTerms = new Set(); const searchTerms = new Set();
@ -284,16 +304,32 @@ const Search = {
// console.info("required: ", [...searchTerms]); // console.info("required: ", [...searchTerms]);
// console.info("excluded: ", [...excludedTerms]); // console.info("excluded: ", [...excludedTerms]);
// array of [docname, title, anchor, descr, score, filename] return [query, searchTerms, excludedTerms, highlightTerms, objectTerms];
let results = []; },
/**
* execute search (requires search index to be loaded)
*/
_performSearch: (query, searchTerms, excludedTerms, highlightTerms, objectTerms) => {
const filenames = Search._index.filenames;
const docNames = Search._index.docnames;
const titles = Search._index.titles;
const allTitles = Search._index.alltitles;
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].
const normalResults = [];
const nonMainIndexResults = [];
_removeChildren(document.getElementById("search-progress")); _removeChildren(document.getElementById("search-progress"));
const queryLower = query.toLowerCase(); const queryLower = query.toLowerCase().trim();
for (const [title, foundTitles] of Object.entries(allTitles)) { for (const [title, foundTitles] of Object.entries(allTitles)) {
if (title.toLowerCase().includes(queryLower) && (queryLower.length >= title.length/2)) { if (title.toLowerCase().trim().includes(queryLower) && (queryLower.length >= title.length/2)) {
for (const [file, id] of foundTitles) { for (const [file, id] of foundTitles) {
let score = Math.round(100 * queryLower.length / title.length) let score = Math.round(100 * queryLower.length / title.length)
results.push([ normalResults.push([
docNames[file], docNames[file],
titles[file] !== title ? `${titles[file]} > ${title}` : title, titles[file] !== title ? `${titles[file]} > ${title}` : title,
id !== null ? "#" + id : "", id !== null ? "#" + id : "",
@ -308,46 +344,47 @@ const Search = {
// search for explicit entries in index directives // search for explicit entries in index directives
for (const [entry, foundEntries] of Object.entries(indexEntries)) { for (const [entry, foundEntries] of Object.entries(indexEntries)) {
if (entry.includes(queryLower) && (queryLower.length >= entry.length/2)) { if (entry.includes(queryLower) && (queryLower.length >= entry.length/2)) {
for (const [file, id] of foundEntries) { for (const [file, id, isMain] of foundEntries) {
let score = Math.round(100 * queryLower.length / entry.length) const score = Math.round(100 * queryLower.length / entry.length);
results.push([ const result = [
docNames[file], docNames[file],
titles[file], titles[file],
id ? "#" + id : "", id ? "#" + id : "",
null, null,
score, score,
filenames[file], filenames[file],
]); ];
if (isMain) {
normalResults.push(result);
} else {
nonMainIndexResults.push(result);
}
} }
} }
} }
// lookup as object // lookup as object
objectTerms.forEach((term) => objectTerms.forEach((term) =>
results.push(...Search.performObjectSearch(term, objectTerms)) normalResults.push(...Search.performObjectSearch(term, objectTerms))
); );
// lookup as search terms in fulltext // lookup as search terms in fulltext
results.push(...Search.performTermsSearch(searchTerms, excludedTerms)); normalResults.push(...Search.performTermsSearch(searchTerms, excludedTerms));
// let the scorer override scores with a custom scoring function // let the scorer override scores with a custom scoring function
if (Scorer.score) results.forEach((item) => (item[4] = Scorer.score(item))); if (Scorer.score) {
normalResults.forEach((item) => (item[4] = Scorer.score(item)));
nonMainIndexResults.forEach((item) => (item[4] = Scorer.score(item)));
}
// now sort the results by score (in opposite order of appearance, since the // Sort each group of results by score and then alphabetically by name.
// display function below uses pop() to retrieve items) and then normalResults.sort(_orderResultsByScoreThenName);
// alphabetically nonMainIndexResults.sort(_orderResultsByScoreThenName);
results.sort((a, b) => {
const leftScore = a[4]; // Combine the result groups in (reverse) order.
const rightScore = b[4]; // Non-main index entries are typically arbitrary cross-references,
if (leftScore === rightScore) { // so display them after other results.
// same score: sort alphabetically let results = [...nonMainIndexResults, ...normalResults];
const leftTitle = a[1].toLowerCase();
const rightTitle = b[1].toLowerCase();
if (leftTitle === rightTitle) return 0;
return leftTitle > rightTitle ? -1 : 1; // inverted is intentional
}
return leftScore > rightScore ? 1 : -1;
});
// remove duplicate search results // remove duplicate search results
// note the reversing of results, so that in the case of duplicates, the highest-scoring entry is kept // note the reversing of results, so that in the case of duplicates, the highest-scoring entry is kept
@ -361,7 +398,12 @@ const Search = {
return acc; return acc;
}, []); }, []);
results = results.reverse(); return results.reverse();
},
query: (query) => {
const [searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms] = Search._parseQuery(query);
const results = Search._performSearch(searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms);
// for debugging // for debugging
//Search.lastresults = results.slice(); // a copy //Search.lastresults = results.slice(); // a copy
@ -466,14 +508,18 @@ const Search = {
// add support for partial matches // add support for partial matches
if (word.length > 2) { if (word.length > 2) {
const escapedWord = _escapeRegExp(word); const escapedWord = _escapeRegExp(word);
Object.keys(terms).forEach((term) => { if (!terms.hasOwnProperty(word)) {
if (term.match(escapedWord) && !terms[word]) Object.keys(terms).forEach((term) => {
arr.push({ files: terms[term], score: Scorer.partialTerm }); if (term.match(escapedWord))
}); arr.push({ files: terms[term], score: Scorer.partialTerm });
Object.keys(titleTerms).forEach((term) => { });
if (term.match(escapedWord) && !titleTerms[word]) }
arr.push({ files: titleTerms[word], score: Scorer.partialTitle }); if (!titleTerms.hasOwnProperty(word)) {
}); Object.keys(titleTerms).forEach((term) => {
if (term.match(escapedWord))
arr.push({ files: titleTerms[term], score: Scorer.partialTitle });
});
}
} }
// no match but word was a required one // no match but word was a required one
@ -496,9 +542,8 @@ const Search = {
// create the mapping // create the mapping
files.forEach((file) => { files.forEach((file) => {
if (fileMap.has(file) && fileMap.get(file).indexOf(word) === -1) if (!fileMap.has(file)) fileMap.set(file, [word]);
fileMap.get(file).push(word); else if (fileMap.get(file).indexOf(word) === -1) fileMap.get(file).push(word);
else fileMap.set(file, [word]);
}); });
}); });
@ -549,8 +594,8 @@ const Search = {
* search summary for a given text. keywords is a list * search summary for a given text. keywords is a list
* of stemmed words. * of stemmed words.
*/ */
makeSearchSummary: (htmlText, keywords) => { makeSearchSummary: (htmlText, keywords, anchor) => {
const text = Search.htmlToText(htmlText); const text = Search.htmlToText(htmlText, anchor);
if (text === "") return null; if (text === "") return null;
const textLower = text.toLowerCase(); const textLower = text.toLowerCase();

View File

@ -16,7 +16,7 @@
<script src="_static/jquery.js?v=5d32c60e"></script> <script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script> <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=664ffad9"></script> <script src="_static/documentation_options.js?v=664ffad9"></script>
<script src="_static/doctools.js?v=888ff710"></script> <script src="_static/doctools.js?v=9a2dae69"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script> <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/js/theme.js"></script> <script src="_static/js/theme.js"></script>
<link rel="author" title="About these documents" href="#" /> <link rel="author" title="About these documents" href="#" />

View File

@ -16,7 +16,7 @@
<script src="_static/jquery.js?v=5d32c60e"></script> <script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script> <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=664ffad9"></script> <script src="_static/documentation_options.js?v=664ffad9"></script>
<script src="_static/doctools.js?v=888ff710"></script> <script src="_static/doctools.js?v=9a2dae69"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script> <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/js/theme.js"></script> <script src="_static/js/theme.js"></script>
<link rel="author" title="About these documents" href="about.html" /> <link rel="author" title="About these documents" href="about.html" />

View File

@ -15,7 +15,7 @@
<script src="_static/jquery.js?v=5d32c60e"></script> <script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script> <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=664ffad9"></script> <script src="_static/documentation_options.js?v=664ffad9"></script>
<script src="_static/doctools.js?v=888ff710"></script> <script src="_static/doctools.js?v=9a2dae69"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script> <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/js/theme.js"></script> <script src="_static/js/theme.js"></script>
<link rel="author" title="About these documents" href="about.html" /> <link rel="author" title="About these documents" href="about.html" />

View File

@ -16,7 +16,7 @@
<script src="_static/jquery.js?v=5d32c60e"></script> <script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script> <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=664ffad9"></script> <script src="_static/documentation_options.js?v=664ffad9"></script>
<script src="_static/doctools.js?v=888ff710"></script> <script src="_static/doctools.js?v=9a2dae69"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script> <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/js/theme.js"></script> <script src="_static/js/theme.js"></script>
<link rel="author" title="About these documents" href="about.html" /> <link rel="author" title="About these documents" href="about.html" />

View File

@ -16,7 +16,7 @@
<script src="_static/jquery.js?v=5d32c60e"></script> <script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script> <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=664ffad9"></script> <script src="_static/documentation_options.js?v=664ffad9"></script>
<script src="_static/doctools.js?v=888ff710"></script> <script src="_static/doctools.js?v=9a2dae69"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script> <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/js/theme.js"></script> <script src="_static/js/theme.js"></script>
<link rel="author" title="About these documents" href="about.html" /> <link rel="author" title="About these documents" href="about.html" />

View File

@ -15,7 +15,7 @@
<script src="_static/jquery.js?v=5d32c60e"></script> <script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script> <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=664ffad9"></script> <script src="_static/documentation_options.js?v=664ffad9"></script>
<script src="_static/doctools.js?v=888ff710"></script> <script src="_static/doctools.js?v=9a2dae69"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script> <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/js/theme.js"></script> <script src="_static/js/theme.js"></script>
<link rel="author" title="About these documents" href="about.html" /> <link rel="author" title="About these documents" href="about.html" />

View File

@ -16,7 +16,7 @@
<script src="_static/jquery.js?v=5d32c60e"></script> <script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script> <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=664ffad9"></script> <script src="_static/documentation_options.js?v=664ffad9"></script>
<script src="_static/doctools.js?v=888ff710"></script> <script src="_static/doctools.js?v=9a2dae69"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script> <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/js/theme.js"></script> <script src="_static/js/theme.js"></script>
<link rel="author" title="About these documents" href="about.html" /> <link rel="author" title="About these documents" href="about.html" />

View File

@ -16,7 +16,7 @@
<script src="_static/jquery.js?v=5d32c60e"></script> <script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script> <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=664ffad9"></script> <script src="_static/documentation_options.js?v=664ffad9"></script>
<script src="_static/doctools.js?v=888ff710"></script> <script src="_static/doctools.js?v=9a2dae69"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script> <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/js/theme.js"></script> <script src="_static/js/theme.js"></script>
<script src="_static/searchtools.js"></script> <script src="_static/searchtools.js"></script>

File diff suppressed because one or more lines are too long