GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — gh-138277: Elevate Built-in Types and Functions in Documentation Search by adqm · Pull Request #138278 · python/cpython

Conversation

@adqm

@adqm adqm commented Aug 31, 2025 •
edited by github-actions Bot
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Contributor

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/

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@adqm
docs search function: give a boost to built-in types and functions
915e580
@adqm
adqm requested review from AA-Turner and hugovk as code owners August 31, 2025 05:13
@bedevere-app bedevere-app Bot added the awaiting review label Aug 31, 2025
@bedevere-app bedevere-app Bot mentioned this pull request Aug 31, 2025
Ordering of search results in the docs could be improved #138277
Closed
@skirpichev

This comment was marked as resolved.

Sign in to view
skirpichev
skirpichev reviewed Aug 31, 2025
View reviewed changes

@skirpichev skirpichev left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
adqm reacted with hooray emoji
All reactions
  • 🎉 1 reaction
Comment thread Doc/search_scorer.js Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/search_scorer.js Resolved

Uh oh!

There was an error while loading. Please reload this page.
adqm added 3 commits August 31, 2025 02:25
@adqm
rearrange scorer code and add comments
2b46b78
@adqm
add news entry
66b736c
@adqm
tweak scoring a bit
97a8c74 
...to try to keep most search results roughly where they currently are.
@adqm

adqm commented Aug 31, 2025

Copy link
Copy Markdown
Contributor Author

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...
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
StanFromIreland
StanFromIreland reviewed Aug 31, 2025
View reviewed changes

@StanFromIreland StanFromIreland left a comment •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
skirpichev and adqm reacted with thumbs up emoji
All reactions
  • 👍 2 reactions
skirpichev
skirpichev approved these changes Aug 31, 2025
View reviewed changes

@skirpichev skirpichev left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/search_scorer.js Resolved

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-app bedevere-app Bot added awaiting core review and removed awaiting review labels Aug 31, 2025
adqm added 2 commits August 31, 2025 06:53
@adqm
remove comment about where customization stops
7e21628
@adqm
move search scorer JS file out of Doc root
8da1ff7
@adqm

adqm commented Aug 31, 2025

Copy link
Copy Markdown
Contributor Author

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@AA-Turner AA-Turner self-assigned this Aug 31, 2025
@github-actions

github-actions Bot commented Apr 28, 2026

Copy link
Copy Markdown

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@github-actions github-actions Bot added the stale Stale PR or inactive for long period of time. label Apr 28, 2026
@StanFromIreland
Merge branch 'main' into search_scoring
2ab5a16
StanFromIreland
StanFromIreland reviewed Sep 8, 2026
View reviewed changes
Comment thread Doc/tools/static/search_scorer.js Outdated
let [docname, title, anchor, descr, score, filename] = result;

// boost the score of built-in functions and types
const builtinPages = ["library/stdtypes", "library/functions"];

@StanFromIreland StanFromIreland Sep 8, 2026

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
adqm reacted with thumbs up emoji
All reactions
  • 👍 1 reaction

@adqm adqm Sep 10, 2026

Copy link
Copy Markdown
Contributor Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@read-the-docs-community

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

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown

Documentation build overview

📚 cpython-previews | 🛠️ Build #35567545 | 📁 Comparing 549d8c3 against main (e757c06)

  🔍 Preview build  

234 files changed · + 9 added · ± 225 modified

+ Added

  • builtins/constants.html
  • builtins/exceptions.html
  • builtins/functions.html
  • builtins/index.html
  • builtins/stdtypes.html
  • builtins/threadsafety.html
  • builtins/time-complexity.html
  • c-api/pyexpat.html
  • library/tkinter.dialogs.html

± Modified

  • glossary.html
  • index.html
  • license.html
  • py-modindex.html
  • _static/tachyon-example-heatmap.html
  • c-api/bool.html
  • c-api/buffer.html
  • c-api/bytearray.html
  • c-api/bytes.html
  • c-api/capsule.html
  • and 215 more...
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@github-actions github-actions Bot removed the stale Stale PR or inactive for long period of time. label Sep 9, 2026
@adqm
add library/exceptions and library/exceptions to pages with boosted s…
4624fdc 
…cores
StanFromIreland
StanFromIreland reviewed Sep 10, 2026
View reviewed changes
Comment thread Doc/tools/static/search_scorer.js Resolved

Uh oh!

There was an error while loading. Please reload this page.
StanFromIreland
StanFromIreland reviewed Sep 10, 2026
View reviewed changes
Comment thread Doc/conf.py Resolved

Uh oh!

There was an error while loading. Please reload this page.
adqm added 2 commits October 9, 2026 08:02
@adqm
move search scoring stuff above config for sphinx extensions in conf.py
0bdf135
@adqm
Revert "remove comment about where customization stops"
00edcd2 
This reverts commit 7e21628.
adqm added 2 commits October 11, 2026 15:43
@adqm
add reference to docs for search scorer
ab0b61d
@adqm
Merge branch 'main' into search_scoring
4df6d89
@adqm

adqm commented Oct 13, 2026

Copy link
Copy Markdown
Contributor Author

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!
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
hugovk
hugovk reviewed Oct 13, 2026
View reviewed changes
Comment thread Doc/tools/static/search_scorer.js Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/tools/static/search_scorer.js Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/tools/static/search_scorer.js Resolved

Uh oh!

There was an error while loading. Please reload this page.
@adqm
point to correct updated place for built-ins
96c60a4
@adqm

adqm commented Oct 13, 2026

Copy link
Copy Markdown
Contributor Author

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?
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
adqm and others added 2 commits October 17, 2026 11:16
@adqm
Merge branch 'main' into search_scoring
f3aea19
@StanFromIreland
Restrict boosted results to objects
549d8c3
StanFromIreland
StanFromIreland reviewed Oct 24, 2026
View reviewed changes

@StanFromIreland StanFromIreland left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@adqm

adqm commented Oct 30, 2026

Copy link
Copy Markdown
Contributor Author

Sorry for being slow here; I'll check out the results of your patch this weekend and get back to you!
StanFromIreland reacted with thumbs up emoji
All reactions
  • 👍 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@adqm

adqm commented Nov 1, 2026

Copy link
Copy Markdown
Contributor Author

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
hugovk
hugovk approved these changes Nov 2, 2026
View reviewed changes

@hugovk hugovk left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you!

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@bedevere-app bedevere-app Bot added awaiting merge and removed awaiting core review labels Nov 2, 2026
@hugovk 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
StanFromIreland approved these changes Nov 2, 2026
View reviewed changes
@StanFromIreland
StanFromIreland merged commit 64e3db7 into python:main Nov 2, 2026
38 checks passed

Uh oh!

There was an error while loading. Please reload this page.
@miss-islington-app

miss-islington-app Bot commented Nov 2, 2026

Copy link
Copy Markdown

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-app bedevere-app Bot removed the awaiting merge label Nov 2, 2026
@StanFromIreland

StanFromIreland commented Nov 2, 2026

Copy link
Copy Markdown
Member

Merged, thanks!
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-app

bedevere-app Bot commented Nov 2, 2026

Copy link
Copy Markdown

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-app bedevere-app Bot removed the needs backport to 3.15 bugs and security fixes label Nov 2, 2026
@bedevere-app

bedevere-app Bot commented Nov 2, 2026

Copy link
Copy Markdown

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-app bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label Nov 2, 2026
StanFromIreland added a commit that referenced this pull request Nov 2, 2026
@miss-islington @adqm @StanFromIreland
[3.15] gh-138277: Elevate Built-in Types and Functions in Documentati…
8668764 
…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]>
StanFromIreland added a commit that referenced this pull request Nov 2, 2026
@miss-islington @adqm @StanFromIreland
[3.14] gh-138277: Elevate Built-in Types and Functions in Documentati…
eb17041 
…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]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@hugovk hugovk hugovk approved these changes
@skirpichev skirpichev skirpichev approved these changes
@StanFromIreland StanFromIreland StanFromIreland approved these changes
@AA-Turner AA-Turner Awaiting requested review from AA-Turner AA-Turner is a code owner

Uh oh!

There was an error while loading. Please reload this page.

Assignees

@AA-Turner AA-Turner

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

5 participants

@adqm @skirpichev @StanFromIreland @hugovk @AA-Turner
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.