[3.14] gh-138277: Elevate Built-in Types and Functions in Documentation Search (GH-138278) (#161197)

(cherry picked from commit 64e3db7)

Co-authored-by: adam j hartz <hz@mit.edu>
Co-authored-by: Stan Ulbrych <stan@python.org>

Author: 3 people

Doc/conf.py

@@ -608,6 +608,11 @@
     r'https://unix.org/version2/whatsnew/lp64_wp.html',
 ]
 
+# Options to adjust search results sorting
+# ----------------------------------------
+
+html_search_scorer = "tools/static/search_scorer.js"
+
 
 # Options for sphinx.ext.extlinks
 # -------------------------------

Doc/tools/static/search_scorer.js

@@ -0,0 +1,40 @@
+var Scorer = {
+  score: function (result) {
+    let [docname, title, anchor, descr, score, filename, kind] = result;
+
+    // boost the score of built-in functions and types
+    const builtinPages = [
+      "builtins/constants",
+      "builtins/exceptions",
+      "builtins/functions",
+      "builtins/stdtypes",
+    ];
+    if (kind === "object" && builtinPages.includes(docname)) {
+      score += 7;
+    }
+
+    return score;
+  },
+
+  // all values below this line are the Sphinx defaults
+  // (see https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_search_scorer)
+
+  // 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,
+    2: -5,
+  },
+  objPrioDefault: 0,
+
+  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
+
+  term: 5, // score if a term exactly matches search query
+  partialTerm: 2, // score if a term contains search query
+};

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.