From 915e58089da963f8e7d38476035394702f12e5f2 Mon Sep 17 00:00:00 2001 From: adam j hartz Date: Fri, 29 Aug 2025 18:03:27 -0400 Subject: [PATCH 1/6] docs search function: give a boost to built-in types and functions --- Doc/conf.py | 5 +++++ Doc/search_scorer.js | 24 ++++++++++++++++++++++++ 2 files changed, 29 insertions(+) create mode 100644 Doc/search_scorer.js diff --git a/Doc/conf.py b/Doc/conf.py index 35e0b3eaeafe94..475de49adce334 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -575,3 +575,8 @@ '', '', ) + +# Options to adjust search results sorting +# ---------------------------------------- + +html_search_scorer = "search_scorer.js" diff --git a/Doc/search_scorer.js b/Doc/search_scorer.js new file mode 100644 index 00000000000000..68167b8ad99a62 --- /dev/null +++ b/Doc/search_scorer.js @@ -0,0 +1,24 @@ +var Scorer = { + score: function (result) { + let [docname, title, anchor, descr, score, filename] = result; + if (docname == "library/stdtypes" || docname == "library/functions") { + score += 10; + } + return score; + }, + + objPrio: { + 0: 15, + 1: 5, + 2: -5, + }, + objPrioDefault: 0, + + objNameMatch: 20, + objPartialMatch: 6, + + title: 15, + partialTitle: 7, + term: 5, + partialTerm: 2, +}; From 2b46b78c909cebd258a8424f039b2aed196582d4 Mon Sep 17 00:00:00 2001 From: adam j hartz Date: Sun, 31 Aug 2025 02:25:03 -0400 Subject: [PATCH 2/6] rearrange scorer code and add comments --- Doc/search_scorer.js | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/Doc/search_scorer.js b/Doc/search_scorer.js index 68167b8ad99a62..578af6b95109e5 100644 --- a/Doc/search_scorer.js +++ b/Doc/search_scorer.js @@ -1,12 +1,21 @@ var Scorer = { score: function (result) { let [docname, title, anchor, descr, score, filename] = result; - if (docname == "library/stdtypes" || docname == "library/functions") { + + // boost the score of built-in functions and types + const builtinPages = ["library/stdtypes", "library/functions"]; + if (builtinPages.includes(docname)) { score += 10; } + return score; }, + // all values below this line are the Sphinx defaults + + // Additive scores depending on the priority of the object + // Priority is set by object domains + // (see https://www.sphinx-doc.org/en/master/extdev/domainapi.html) objPrio: { 0: 15, 1: 5, @@ -14,11 +23,12 @@ var Scorer = { }, objPrioDefault: 0, - objNameMatch: 20, - objPartialMatch: 6, + objNameMatch: 11, // score if object's name exactly matches search query + objPartialMatch: 6, // score if object's name contains search query + + title: 15, // score if title exactly matches search query + partialTitle: 7, // score if title contains search query - title: 15, - partialTitle: 7, - term: 5, - partialTerm: 2, + term: 5, // score if a term exactly matches search query + partialTerm: 2, // score if a term contains search query }; From 66b736ccc63a0e38c086208be0774ceae72bc634 Mon Sep 17 00:00:00 2001 From: adam j hartz Date: Sun, 31 Aug 2025 02:28:27 -0400 Subject: [PATCH 3/6] add news entry --- .../2025-08-31-02-28-21.gh-issue-138277.kkORph.rst | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 Misc/NEWS.d/next/Documentation/2025-08-31-02-28-21.gh-issue-138277.kkORph.rst diff --git a/Misc/NEWS.d/next/Documentation/2025-08-31-02-28-21.gh-issue-138277.kkORph.rst b/Misc/NEWS.d/next/Documentation/2025-08-31-02-28-21.gh-issue-138277.kkORph.rst new file mode 100644 index 00000000000000..198d1de3121c5b --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2025-08-31-02-28-21.gh-issue-138277.kkORph.rst @@ -0,0 +1,2 @@ +Rearranged documentation search results to emphasize built-in types and +functions. Patch by Adam Hartz. From 97a8c742b92fb6d92f4c3d80c5c744e571cc39b7 Mon Sep 17 00:00:00 2001 From: adam j hartz Date: Sun, 31 Aug 2025 02:37:43 -0400 Subject: [PATCH 4/6] tweak scoring a bit ...to try to keep most search results roughly where they currently are. --- Doc/search_scorer.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/search_scorer.js b/Doc/search_scorer.js index 578af6b95109e5..328b20cfb9ca3f 100644 --- a/Doc/search_scorer.js +++ b/Doc/search_scorer.js @@ -5,7 +5,7 @@ var Scorer = { // boost the score of built-in functions and types const builtinPages = ["library/stdtypes", "library/functions"]; if (builtinPages.includes(docname)) { - score += 10; + score += 7; } return score; From 7e216283f1c7a9567b2bdd863d50cd6f31d6c462 Mon Sep 17 00:00:00 2001 From: adam j hartz Date: Sun, 31 Aug 2025 06:53:18 -0400 Subject: [PATCH 5/6] remove comment about where customization stops --- Doc/search_scorer.js | 2 -- 1 file changed, 2 deletions(-) diff --git a/Doc/search_scorer.js b/Doc/search_scorer.js index 328b20cfb9ca3f..03cd6274079ffd 100644 --- a/Doc/search_scorer.js +++ b/Doc/search_scorer.js @@ -11,8 +11,6 @@ var Scorer = { return score; }, - // all values below this line are the Sphinx defaults - // Additive scores depending on the priority of the object // Priority is set by object domains // (see https://www.sphinx-doc.org/en/master/extdev/domainapi.html) From 8da1ff7ddd7881133412773b2f813f1a4be57bba Mon Sep 17 00:00:00 2001 From: adam j hartz Date: Sun, 31 Aug 2025 06:55:33 -0400 Subject: [PATCH 6/6] move search scorer JS file out of Doc root --- Doc/conf.py | 2 +- Doc/{ => tools/static}/search_scorer.js | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename Doc/{ => tools/static}/search_scorer.js (100%) diff --git a/Doc/conf.py b/Doc/conf.py index 475de49adce334..8eb2dd8cb63325 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -579,4 +579,4 @@ # Options to adjust search results sorting # ---------------------------------------- -html_search_scorer = "search_scorer.js" +html_search_scorer = "tools/static/search_scorer.js" diff --git a/Doc/search_scorer.js b/Doc/tools/static/search_scorer.js similarity index 100% rename from Doc/search_scorer.js rename to Doc/tools/static/search_scorer.js