From 551b4ae7d284b42c2e9db3622519c80e8ac8ad0b Mon Sep 17 00:00:00 2001 From: Michał Górny Date: Sun, 12 May 2024 14:48:19 +0200 Subject: Update Guide to 3b49e09 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Michał Górny --- guide/.buildinfo | 2 +- guide/_sources/distutils.rst.txt | 13 ++- guide/_static/basic.css | 2 +- guide/_static/doctools.js | 2 +- guide/_static/language_data.js | 4 +- guide/_static/searchtools.js | 165 +++++++++++++++++++++++-------------- guide/any.html | 8 +- guide/basic.html | 8 +- guide/buildsys.html | 8 +- guide/concept.html | 8 +- guide/depend.html | 8 +- guide/distutils-legacy.html | 8 +- guide/distutils.html | 18 +++- guide/eclass.html | 8 +- guide/expert-multi.html | 8 +- guide/genindex.html | 8 +- guide/helper.html | 8 +- guide/index.html | 8 +- guide/interpreter-maintenance.html | 8 +- guide/interpreter.html | 8 +- guide/migration.html | 8 +- guide/multi.html | 8 +- guide/objects.inv | Bin 896 -> 896 bytes guide/package-maintenance.html | 8 +- guide/porting.html | 8 +- guide/preface.html | 8 +- guide/pypi.html | 10 +-- guide/pytest.html | 8 +- guide/qawarn.html | 8 +- guide/search.html | 14 ++-- guide/searchindex.js | 2 +- guide/single.html | 8 +- guide/test.html | 8 +- 33 files changed, 236 insertions(+), 172 deletions(-) diff --git a/guide/.buildinfo b/guide/.buildinfo index 432e4e8..0aebc93 100644 --- a/guide/.buildinfo +++ b/guide/.buildinfo @@ -1,4 +1,4 @@ # Sphinx build info version 1 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. -config: ca328a06ae0e553a208ded759fc82596 +config: ae4182fbca2b572010c7813755d8102d tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/guide/_sources/distutils.rst.txt b/guide/_sources/distutils.rst.txt index 8101d8b..fa4f77e 100644 --- a/guide/_sources/distutils.rst.txt +++ b/guide/_sources/distutils.rst.txt @@ -1038,10 +1038,16 @@ the crate licenses in addition to the Python package's license. to prevent false positives on ignored ``CFLAGS`` and ``LDFLAGS`` warnings. Finally, the ebuild needs to call ``cargo_src_unpack``. +Note that some Rust/Python packages use both Rust-level and Python-level +tests. To check for this, it is a good idea to run ``cargo test`` +manually and see if any tests are run. If they are, ``cargo_src_test`` +should be called in ``python_test_all()`` (or possibly ``python_test()`` +if they specifically use Python linkage). + An example ebuild follows: .. code-block:: bash - :emphasize-lines: 6,10-15,17,23,28,31,35,38 + :emphasize-lines: 6,10-15,17,23,28,31,35,38,43 # Copyright 2022 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 @@ -1083,6 +1089,11 @@ An example ebuild follows: cargo_src_unpack } + python_test_all() { + cd src/rust || die + cargo_src_test + } + Installing packages without a PEP 517 build backend =================================================== diff --git a/guide/_static/basic.css b/guide/_static/basic.css index 4157edf..e5179b7 100644 --- a/guide/_static/basic.css +++ b/guide/_static/basic.css @@ -4,7 +4,7 @@ * * 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. * */ diff --git a/guide/_static/doctools.js b/guide/_static/doctools.js index d06a71d..4d67807 100644 --- a/guide/_static/doctools.js +++ b/guide/_static/doctools.js @@ -4,7 +4,7 @@ * * 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. * */ diff --git a/guide/_static/language_data.js b/guide/_static/language_data.js index 250f566..367b8ed 100644 --- a/guide/_static/language_data.js +++ b/guide/_static/language_data.js @@ -5,7 +5,7 @@ * This script contains the language-specific data used by searchtools.js, * 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. * */ @@ -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"]; -/* 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 diff --git a/guide/_static/searchtools.js b/guide/_static/searchtools.js index 7918c3f..92da3f8 100644 --- a/guide/_static/searchtools.js +++ b/guide/_static/searchtools.js @@ -4,7 +4,7 @@ * * 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. * */ @@ -99,7 +99,7 @@ const _displayItem = (item, searchTerms, highlightTerms) => { .then((data) => { if (data) listItem.appendChild( - Search.makeSearchSummary(data, searchTerms) + Search.makeSearchSummary(data, searchTerms, anchor) ); // highlight search terms in the summary if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js @@ -116,8 +116,8 @@ const _finishSearch = (resultCount) => { ); else 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 = ( results, @@ -137,6 +137,22 @@ const _displayNextItem = ( // search finished, update title and status message 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 @@ -160,13 +176,26 @@ const Search = { _queued_query: null, _pulse_status: -1, - htmlToText: (htmlString) => { + htmlToText: (htmlString, anchor) => { 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"]'); - if (docContent !== undefined) return docContent.textContent; + if (docContent) return docContent.textContent; + 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 ""; }, @@ -239,16 +268,7 @@ const Search = { else Search.deferQuery(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; - + _parseQuery: (query) => { // stem the search terms and add them to the correct list const stemmer = new Stemmer(); const searchTerms = new Set(); @@ -284,16 +304,32 @@ const Search = { // console.info("required: ", [...searchTerms]); // console.info("excluded: ", [...excludedTerms]); - // array of [docname, title, anchor, descr, score, filename] - let results = []; + return [query, searchTerms, excludedTerms, highlightTerms, objectTerms]; + }, + + /** + * 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")); - const queryLower = query.toLowerCase(); + const queryLower = query.toLowerCase().trim(); 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) { let score = Math.round(100 * queryLower.length / title.length) - results.push([ + normalResults.push([ docNames[file], titles[file] !== title ? `${titles[file]} > ${title}` : title, id !== null ? "#" + id : "", @@ -308,46 +344,47 @@ const Search = { // search for explicit entries in index directives for (const [entry, foundEntries] of Object.entries(indexEntries)) { if (entry.includes(queryLower) && (queryLower.length >= entry.length/2)) { - for (const [file, id] of foundEntries) { - let score = Math.round(100 * queryLower.length / entry.length) - results.push([ + for (const [file, id, isMain] of foundEntries) { + const score = Math.round(100 * queryLower.length / entry.length); + const result = [ docNames[file], titles[file], id ? "#" + id : "", null, score, filenames[file], - ]); + ]; + if (isMain) { + normalResults.push(result); + } else { + nonMainIndexResults.push(result); + } } } } // lookup as object objectTerms.forEach((term) => - results.push(...Search.performObjectSearch(term, objectTerms)) + normalResults.push(...Search.performObjectSearch(term, objectTerms)) ); // 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 - if (Scorer.score) results.forEach((item) => (item[4] = Scorer.score(item))); - - // now sort the results by score (in opposite order of appearance, since the - // display function below uses pop() to retrieve items) and then - // alphabetically - results.sort((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; - }); + if (Scorer.score) { + normalResults.forEach((item) => (item[4] = Scorer.score(item))); + nonMainIndexResults.forEach((item) => (item[4] = Scorer.score(item))); + } + + // Sort each group of results by score and then alphabetically by name. + normalResults.sort(_orderResultsByScoreThenName); + nonMainIndexResults.sort(_orderResultsByScoreThenName); + + // Combine the result groups in (reverse) order. + // Non-main index entries are typically arbitrary cross-references, + // so display them after other results. + let results = [...nonMainIndexResults, ...normalResults]; // remove duplicate search results // 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; }, []); - 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 //Search.lastresults = results.slice(); // a copy @@ -466,14 +508,18 @@ const Search = { // add support for partial matches if (word.length > 2) { const escapedWord = _escapeRegExp(word); - Object.keys(terms).forEach((term) => { - if (term.match(escapedWord) && !terms[word]) - 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 (!terms.hasOwnProperty(word)) { + Object.keys(terms).forEach((term) => { + if (term.match(escapedWord)) + arr.push({ files: terms[term], score: Scorer.partialTerm }); + }); + } + 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 @@ -496,9 +542,8 @@ const Search = { // create the mapping files.forEach((file) => { - if (fileMap.has(file) && fileMap.get(file).indexOf(word) === -1) - fileMap.get(file).push(word); - else fileMap.set(file, [word]); + if (!fileMap.has(file)) fileMap.set(file, [word]); + else if (fileMap.get(file).indexOf(word) === -1) fileMap.get(file).push(word); }); }); @@ -549,8 +594,8 @@ const Search = { * search summary for a given text. keywords is a list * of stemmed words. */ - makeSearchSummary: (htmlText, keywords) => { - const text = Search.htmlToText(htmlText); + makeSearchSummary: (htmlText, keywords, anchor) => { + const text = Search.htmlToText(htmlText, anchor); if (text === "") return null; const textLower = text.toLowerCase(); diff --git a/guide/any.html b/guide/any.html index 49c5623..7b116c5 100644 --- a/guide/any.html +++ b/guide/any.html @@ -9,7 +9,7 @@ - + @@ -351,7 +351,7 @@ USE conditional blocks inside - + @@ -377,7 +377,7 @@ USE conditional blocks inside Sphinx 7.2.6 + Powered by Sphinx 7.3.7 & Alabaster 0.7.16 | diff --git a/guide/basic.html b/guide/basic.html index 0cb70b6..df634da 100644 --- a/guide/basic.html +++ b/guide/basic.html @@ -9,7 +9,7 @@ - + @@ -313,7 +313,7 @@ or noxfile.py - + @@ -339,7 +339,7 @@ or noxfile.pySphinx 7.2.6 + Powered by Sphinx 7.3.7 & Alabaster 0.7.16 | diff --git a/guide/buildsys.html b/guide/buildsys.html index f2f394e..d881435 100644 --- a/guide/buildsys.html +++ b/guide/buildsys.html @@ -9,7 +9,7 @@ - + @@ -705,7 +705,7 @@ build-time ${PYTHON - + @@ -731,7 +731,7 @@ build-time ${PYTHON ©2020, Michał Górny, license: CC BY 4.0. | - Powered by Sphinx 7.2.6 + Powered by Sphinx 7.3.7 & Alabaster 0.7.16 | diff --git a/guide/concept.html b/guide/concept.html index 59e7032..902ef05 100644 --- a/guide/concept.html +++ b/guide/concept.html @@ -9,7 +9,7 @@ - + @@ -249,7 +249,7 @@ of being retired.

- + @@ -275,7 +275,7 @@ of being retired.

©2020, Michał Górny, license: CC BY 4.0. | - Powered by Sphinx 7.2.6 + Powered by Sphinx 7.3.7 & Alabaster 0.7.16 | diff --git a/guide/depend.html b/guide/depend.html index 09e7958..0c567e2 100644 --- a/guide/depend.html +++ b/guide/depend.html @@ -9,7 +9,7 @@ - + @@ -323,7 +323,7 @@ to run them.

- + @@ -349,7 +349,7 @@ to run them.

©2020, Michał Górny, license: CC BY 4.0. | - Powered by Sphinx 7.2.6 + Powered by Sphinx 7.3.7 & Alabaster 0.7.16 | diff --git a/guide/distutils-legacy.html b/guide/distutils-legacy.html index dea7464..186e8e4 100644 --- a/guide/distutils-legacy.html +++ b/guide/distutils-legacy.html @@ -9,7 +9,7 @@ - + @@ -382,7 +382,7 @@ has broken it for most of the consumers.

- + @@ -408,7 +408,7 @@ has broken it for most of the consumers.

©2020, Michał Górny, license: CC BY 4.0. | - Powered by Sphinx 7.2.6 + Powered by Sphinx 7.3.7 & Alabaster 0.7.16 | diff --git a/guide/distutils.html b/guide/distutils.html index 45d13d2..b35d053 100644 --- a/guide/distutils.html +++ b/guide/distutils.html @@ -9,7 +9,7 @@ - + @@ -952,6 +952,11 @@ the crate licenses in addition to the Python package’s license. QA_FLAGS_IGNORED needs to match all Rust extensions in order to prevent false positives on ignored CFLAGS and LDFLAGS warnings. Finally, the ebuild needs to call cargo_src_unpack.

+

Note that some Rust/Python packages use both Rust-level and Python-level +tests. To check for this, it is a good idea to run cargo test +manually and see if any tests are run. If they are, cargo_src_test +should be called in python_test_all() (or possibly python_test() +if they specifically use Python linkage).

An example ebuild follows:

 # Copyright 2022 Gentoo Authors
  # Distributed under the terms of the GNU General Public License v2
@@ -992,6 +997,11 @@ warnings.  Finally, the ebuild needs to call  src_unpack() {
      cargo_src_unpack
  }
+
+ python_test_all() {
+     cd src/rust || die
+     cargo_src_test
+ }
@@ -1214,7 +1224,7 @@ python_install() { - + @@ -1240,7 +1250,7 @@ python_install() { ©2020, Michał Górny, license: CC BY 4.0. | - Powered by Sphinx 7.2.6 + Powered by Sphinx 7.3.7 & Alabaster 0.7.16 | diff --git a/guide/eclass.html b/guide/eclass.html index d7af3d6..30c2a44 100644 --- a/guide/eclass.html +++ b/guide/eclass.html @@ -9,7 +9,7 @@ - + @@ -223,7 +223,7 @@ For single-impl packages, - + @@ -249,7 +249,7 @@ For single-impl packages, Sphinx 7.2.6 + Powered by Sphinx 7.3.7 & Alabaster 0.7.16 | diff --git a/guide/expert-multi.html b/guide/expert-multi.html index 74b8a4c..36877c7 100644 --- a/guide/expert-multi.html +++ b/guide/expert-multi.html @@ -9,7 +9,7 @@ - + @@ -602,7 +602,7 @@ to python_gen_any_d - + @@ -628,7 +628,7 @@ to python_gen_any_d ©2020, Michał Górny, license: CC BY 4.0. | - Powered by Sphinx 7.2.6 + Powered by Sphinx 7.3.7 & Alabaster 0.7.16 | diff --git a/guide/genindex.html b/guide/genindex.html index 5d9af7f..907fbfa 100644 --- a/guide/genindex.html +++ b/guide/genindex.html @@ -8,7 +8,7 @@ - + @@ -375,7 +375,7 @@ - + @@ -401,7 +401,7 @@ ©2020, Michał Górny, license: CC BY 4.0. | - Powered by Sphinx 7.2.6 + Powered by Sphinx 7.3.7 & Alabaster 0.7.16 diff --git a/guide/helper.html b/guide/helper.html index dfe05be..7f38476 100644 --- a/guide/helper.html +++ b/guide/helper.html @@ -9,7 +9,7 @@ - + @@ -316,7 +316,7 @@ helpers instead.

- + @@ -342,7 +342,7 @@ helpers instead.

©2020, Michał Górny, license: CC BY 4.0. | - Powered by Sphinx 7.2.6 + Powered by Sphinx 7.3.7 & Alabaster 0.7.16 | diff --git a/guide/index.html b/guide/index.html index 672c640..4c0d97d 100644 --- a/guide/index.html +++ b/guide/index.html @@ -9,7 +9,7 @@ - + @@ -292,7 +292,7 @@ - + @@ -318,7 +318,7 @@ ©2020, Michał Górny, license: CC BY 4.0. | - Powered by Sphinx 7.2.6 + Powered by Sphinx 7.3.7 & Alabaster 0.7.16 | diff --git a/guide/interpreter-maintenance.html b/guide/interpreter-maintenance.html index 3863ab5..0f648f9 100644 --- a/guide/interpreter-maintenance.html +++ b/guide/interpreter-maintenance.html @@ -9,7 +9,7 @@ - + @@ -366,7 +366,7 @@ dependencies will be added or vendored into flit_core.

- + @@ -392,7 +392,7 @@ dependencies will be added or vendored into flit_core.

©2020, Michał Górny, license: CC BY 4.0. | - Powered by Sphinx 7.2.6 + Powered by Sphinx 7.3.7 & Alabaster 0.7.16 | diff --git a/guide/interpreter.html b/guide/interpreter.html index 067ce79..36d9768 100644 --- a/guide/interpreter.html +++ b/guide/interpreter.html @@ -9,7 +9,7 @@ - + @@ -335,7 +335,7 @@ syntax than native asyncio code.

- + @@ -361,7 +361,7 @@ syntax than native asyncio code.

©2020, Michał Górny, license: CC BY 4.0. | - Powered by Sphinx 7.2.6 + Powered by Sphinx 7.3.7 & Alabaster 0.7.16 | diff --git a/guide/migration.html b/guide/migration.html index f3a4e1a..72e866e 100644 --- a/guide/migration.html +++ b/guide/migration.html @@ -9,7 +9,7 @@ - + @@ -285,7 +285,7 @@ necessary and tests should work out of the box.

- + @@ -311,7 +311,7 @@ necessary and tests should work out of the box.

©2020, Michał Górny, license: CC BY 4.0. | - Powered by Sphinx 7.2.6 + Powered by Sphinx 7.3.7 & Alabaster 0.7.16 | diff --git a/guide/multi.html b/guide/multi.html index a1a60e5..2d43893 100644 --- a/guide/multi.html +++ b/guide/multi.html @@ -9,7 +9,7 @@ - + @@ -428,7 +428,7 @@ flag, while parts affecting build time (