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 #35567545 | 📁 Comparing 549d8c3 against main (e757c06)

🔍 Preview build

234 files changed · + 9 added · ± 225 modified

+ Added

± Modified

…cores

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!

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?

StanFromIreland

I have a little suggestion to avoid elevating non-object results: adqm#2

adqm · 2026-10-30T01:36:51Z

Sorry for being slow here; I'll check out the results of your patch this weekend and get back to you!

adqm · 2026-11-01T23:36:35Z

that change looks good to me, @StanFromIreland ! i just merged it in.

hugovk

Thank you!

miss-islington-app · 2026-11-02T16:52:48Z

Thanks @adqm for the PR, and @StanFromIreland for merging it 🌮🎉.. I'm working now to backport this PR to: 3.14, 3.15.
🐍🍒⛏🤖

StanFromIreland · 2026-11-02T16:52:54Z

Merged, thanks!

bedevere-app · 2026-11-02T16:53:04Z

GH-161196 is a backport of this pull request to the 3.15 branch.

bedevere-app · 2026-11-02T16:53:11Z

GH-161197 is a backport of this pull request to the 3.14 branch.

…on Search (GH-138278) (#161196) (cherry picked from commit 64e3db7) Co-authored-by: adam j hartz <[email protected]> Co-authored-by: Stan Ulbrych <[email protected]>

…on Search (GH-138278) (#161197) (cherry picked from commit 64e3db7) Co-authored-by: adam j hartz <[email protected]> Co-authored-by: Stan Ulbrych <[email protected]>

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

Closed

This comment was marked as resolved.

Sign in to view

skirpichev reviewed Aug 31, 2025

View reviewed changes

Comment thread Doc/search_scorer.js Resolved

Comment thread Doc/search_scorer.js Resolved

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 Resolved

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

Comment thread Doc/tools/static/search_scorer.js Resolved

StanFromIreland reviewed Sep 10, 2026

View reviewed changes

Comment thread Doc/conf.py Resolved

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

Comment thread Doc/tools/static/search_scorer.js Resolved

Comment thread Doc/tools/static/search_scorer.js Resolved

Comment thread Doc/tools/static/search_scorer.js Resolved

point to correct updated place for built-ins

96c60a4

adqm and others added 2 commits October 17, 2026 11:16

Merge branch 'main' into search_scoring

f3aea19

Restrict boosted results to objects

549d8c3

StanFromIreland reviewed Oct 24, 2026

View reviewed changes

hugovk approved these changes Nov 2, 2026

View reviewed changes

bedevere-app Bot added awaiting merge and removed awaiting core review labels Nov 2, 2026

hugovk added needs backport to 3.14 bugs and security fixes needs backport to 3.15 bugs and security fixes labels Nov 2, 2026

StanFromIreland approved these changes Nov 2, 2026

View reviewed changes

StanFromIreland merged commit 64e3db7 into python:main Nov 2, 2026
38 checks passed

bedevere-app Bot removed the awaiting merge label Nov 2, 2026

bedevere-app Bot removed the needs backport to 3.15 bugs and security fixes label Nov 2, 2026

bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label Nov 2, 2026

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!

StanFromIreland Sep 8, 2026

Choose a reason for hiding this comment

Uh oh!

adqm Sep 10, 2026

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!

Uh oh!

Uh oh!

adqm commented Oct 13, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

adqm commented Oct 13, 2026

Uh oh!

StanFromIreland left a comment

Choose a reason for hiding this comment

Uh oh!

adqm commented Oct 30, 2026

Uh oh!

adqm commented Nov 1, 2026

Uh oh!

hugovk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

miss-islington-app Bot commented Nov 2, 2026

Uh oh!

StanFromIreland commented Nov 2, 2026

Uh oh!

bedevere-app Bot commented Nov 2, 2026

Uh oh!

bedevere-app Bot commented Nov 2, 2026

Uh oh!

Reviewers

Uh oh!

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