gh-138277: Elevate Built-in Types and Functions in Documentation Search by adqm · Pull Request #138278 · python/cpython

adqm · 2025-08-31T05:13:07Z

This patch adds a custom search scorer for the Python docs, in the hopes of making the search results more useful. For now, this just increases the score of built-in functions and types so that they show up closer to the top of the relevant search results, though it also opens the door to other improvements. I also have a couple of other ideas that might further improve the ordering, but I figured it'd be best to start small.

With this change:

When searching "str", the built-in str type goes from being the 44th result to the 1st.
When searching "set", the built-in set type goes from being the 14th result to the 1st.
When searching "int", the built-in int type now shows up above tkinter and pprint.

I don't think this needs a news item, but I can add one if y'all think it's necessary.

Issue: Ordering of search results in the docs could be improved #138277

📚 Documentation preview 📚: https://cpython-previews--138278.org.readthedocs.build/

skirpichev

I'm played with this a bit and I generally like new search output 👍

...to try to keep most search results roughly where they currently are.

adqm · 2025-08-31T06:43:43Z

Thanks for taking a look, @skirpichev! I just pushed a few changes, adding some comments and tweaking the scoring a little bit (to adjust one value that I inadvertently changed from the sphinx defaults that was affecting the ordering more than I intended).

Looking around a bit more, though, I am wondering if it might be better to do this with a Sphinx object domain, though, setting the builtin things to be important. But I'm not sure if there's an easy way to do that without hard-coding all of the built-in objects somewhere. @AA-Turner might know better. Then again, some of the other changes I had been thinking of probably do require a score function anyway...

StanFromIreland

The file does not belong in the root Doc dir, please move it to Doc/tools/static.

skirpichev

Look good for me, modulo Stan's comment.

I am wondering if it might be better to do this with a Sphinx object domain, though, setting the builtin things to be important

Probably, the right way might be a mixture of both.

adqm · 2025-08-31T11:12:40Z

Thanks! I went ahead and moved the file into tools/static and removed that comment.

github-actions · 2026-04-28T18:31:26Z

This PR is stale because it has been open for 30 days with no activity.

StanFromIreland · 2026-09-08T19:28:08Z

+    let [docname, title, anchor, descr, score, filename] = result;
+
+    // boost the score of built-in functions and types
+    const builtinPages = ["library/stdtypes", "library/functions"];


Let's add library/exceptions and library/constants.

Thanks for taking a look, and good call! I just added those and pushed.

read-the-docs-community · 2026-09-08T19:29:07Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #35105354 | 📁 Comparing 4df6d89 against main (e757c06)

🔍 Preview build

128 files changed · + 8 added · ± 120 modified

+ Added

± Modified

…cores

StanFromIreland · 2026-09-10T15:38:56Z

+
+    return score;
+  },
+


Please add a comment clarifying these are the defaults, as per the docs.

Sorry to be a while getting back to this. I did used to have a comment in there saying exactly this but removed it after an earlier code review comment (in 7e21628). Should I put it back?

I'd prefer to have it.

Sounds good. I just added that comment back (along with a reference to the Sphinx docs).

StanFromIreland · 2026-09-10T15:39:39Z

        '<meta property="og:image:height" content="200">',
    )
+
+# Options to adjust search results sorting


Please move this up, above configuration for the various extensions, beside the Sphinx adjustments.

This reverts commit 7e21628.

adqm · 2026-10-13T00:40:58Z

I'm not sure what was causing the CI failure before, but merging from main seems to have fixed it. If you want any other changes here, just let me know!

hugovk · 2026-10-13T07:36:38Z

@@ -0,0 +1,40 @@
+var Scorer = {


Can we use const or let instead of var?

We actually need var here because of some stuff inside of Sphinx. I just tried again (both const and let) and was getting errors from Sphinx's searchtools.js, which conditionally defines Scorer if it isn't already defined (see here).

hugovk · 2026-10-13T07:40:19Z

+    let [docname, title, anchor, descr, score, filename] = result;
+
+    // boost the score of built-in functions and types
+    const builtinPages = [


Following #156682, builtins have been split out. Update to include?

Also alphabetise these.

Thanks; just updated now (this patch didn't really do much without pointing to the updated page locations!).

hugovk · 2026-10-13T07:40:56Z

+      "library/constants",
+    ];
+    if (builtinPages.includes(docname)) {
+      score += 7;


I'm curious why a value of 7?

It wasn't a terribly scientific process. IIRC, I tried 5 and it didn't push int or set to the top of their search pages, so I tried a couple of different values until I was generally happy with where the built-ins landed.

adqm · 2026-10-13T11:32:31Z

Not sure why the readthedocs build is failing (it looks like it somehow couldn't find that most recent commit?). Is there a way to force it to try again?

docs search function: give a boost to built-in types and functions

915e580

adqm requested review from AA-Turner and hugovk as code owners August 31, 2025 05:13

bedevere-app Bot added the awaiting review label Aug 31, 2025

bedevere-app Bot mentioned this pull request Aug 31, 2025

Ordering of search results in the docs could be improved #138277

Open

This comment was marked as resolved.

Sign in to view

skirpichev reviewed Aug 31, 2025

View reviewed changes

Comment thread Doc/search_scorer.js Outdated

Comment thread Doc/search_scorer.js Outdated

adqm added 3 commits August 31, 2025 02:25

rearrange scorer code and add comments

2b46b78

add news entry

66b736c

tweak scoring a bit

97a8c74

...to try to keep most search results roughly where they currently are.

StanFromIreland reviewed Aug 31, 2025

View reviewed changes

skirpichev approved these changes Aug 31, 2025

View reviewed changes

Comment thread Doc/search_scorer.js

bedevere-app Bot added awaiting core review and removed awaiting review labels Aug 31, 2025

adqm added 2 commits August 31, 2025 06:53

remove comment about where customization stops

7e21628

move search scorer JS file out of Doc root

8da1ff7

AA-Turner self-assigned this Aug 31, 2025

github-actions Bot added the stale Stale PR or inactive for long period of time. label Apr 28, 2026

Merge branch 'main' into search_scoring

2ab5a16

StanFromIreland reviewed Sep 8, 2026

View reviewed changes

github-actions Bot removed the stale Stale PR or inactive for long period of time. label Sep 9, 2026

add library/exceptions and library/exceptions to pages with boosted s…

4624fdc

…cores

StanFromIreland reviewed Sep 10, 2026

View reviewed changes

adqm added 2 commits October 9, 2026 08:02

move search scoring stuff above config for sphinx extensions in conf.py

0bdf135

Revert "remove comment about where customization stops"

00edcd2

This reverts commit 7e21628.

adqm added 2 commits October 11, 2026 15:43

add reference to docs for search scorer

ab0b61d

Merge branch 'main' into search_scoring

4df6d89

hugovk reviewed Oct 13, 2026

View reviewed changes

point to correct updated place for built-ins

96c60a4

Conversation

adqm commented Aug 31, 2025 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as resolved.

skirpichev left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

adqm commented Aug 31, 2025

Uh oh!

StanFromIreland left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

skirpichev left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

adqm commented Aug 31, 2025

Uh oh!

github-actions Bot commented Apr 28, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

read-the-docs-community Bot commented Sep 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adqm Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adqm commented Oct 13, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adqm commented Oct 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

adqm commented Aug 31, 2025 •

edited by github-actions Bot

Loading

StanFromIreland left a comment •

edited

Loading

read-the-docs-community Bot commented Sep 8, 2026 •

edited

Loading

adqm Oct 9, 2026 •

edited

Loading