FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

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

  1. python
  2. cpython

Repository navigation

gh-138277: Elevate Built-in Types and Functions in Documentation Search - #138278

Open
adqm wants to merge 14 commits into
python:mainfrom
adqm:search_scoring
ConversationCommits (14)ChecksFiles changed
Open

gh-138277: Elevate Built-in Types and Functions in Documentation Search#138278
adqm wants to merge 14 commits into
python:mainfrom
adqm:search_scoring

Conversation

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

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.

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

adqm requested review from AA-Turner and hugovk as code owners August 31, 2025 05:13
bedevere-app Bot mentioned this pull request Aug 31, 2025
Open

This comment was marked as resolved.

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

skirpichev left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

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

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.

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

StanFromIreland reviewed Aug 31, 2025
View reviewed changes

StanFromIreland left a comment •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

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

skirpichev approved these changes Aug 31, 2025
View reviewed changes

skirpichev left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

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.

Comment thread Doc/search_scorer.js

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.

AA-Turner self-assigned this Aug 31, 2025

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.

github-actions Bot added the stale Stale PR or inactive for long period of time. label Apr 28, 2026
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 Sep 8, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

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

adqm Sep 10, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

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

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

Copy link
Copy Markdown

Documentation build overview

📚 cpython-previews | 🛠️ Build #35211463 | 📁 Comparing f3aea19 against main (e757c06)

  🔍 Preview build  

165 files changed · + 8 added · ± 157 modified

+ Added

± Modified

github-actions Bot removed the stale Stale PR or inactive for long period of time. label Sep 9, 2026
StanFromIreland reviewed Sep 10, 2026
View reviewed changes
Comment thread Doc/conf.py Outdated

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!

hugovk reviewed Oct 13, 2026
View reviewed changes
Comment thread Doc/tools/static/search_scorer.js
Comment thread Doc/tools/static/search_scorer.js
Comment thread Doc/tools/static/search_scorer.js

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?

StanFromIreland reviewed Oct 24, 2026
View reviewed changes

StanFromIreland left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

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

This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

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

Assignees

AA-Turner

Labels

awaiting core review

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

Back | FazBrowse Home | New Git URL