Repository navigation
Ordering of search results in the docs could be improved #138277
Description
When searching for "str" in the documentation, for example, the built-in str type shows up 44th in the list of results currently. This specific example (as well as a general notion that the search results are often not useful) was recently cited to me by a colleague as one reason that they choose to caution beginner students against using Python's docs compared to other alternatives, because the docs are "hard to navigate" and "hard to search." I disagree with that assessment on the whole, but I do think that improving the ordering of the search results would make the docs easier to use and navigate, particularly for folks just starting out with Python.
Sphinx has a mechanism for custom sorting of search results, so it should be possible to come up with some heuristics there that improve the ordering of the results. I'll put in a PR in a little while with one small step that I think is an improvement.
Activity
skirpichev commentedon Aug 31, 2025
Prior issue: #86272
Maybe this worth first a more wide discussion on https://discuss.python.org/c/documentation/26
adqm commentedon Aug 31, 2025
Thanks! I agree that a discussion on Discourse is a good idea. I'm tempted to put together a more-complete implementation of more of my ideas before opening a thread there, though; I'm mildly concerned that a discussion in the abstract could lead to a bunch of back-and-forth with no real motion, whereas a concrete implementation to poke holes in might help to keep things focused.
skirpichev commentedon Aug 31, 2025
Well, there are open issues, so feel free to create prs.
Discussion should attract a wider audience and you always can provide concrete implementations e.g. as pr's against your CPython fork. Sure, it's always better if you could formalize your idea with code.
A-UNDERSCORE-D commentedon Aug 31, 2025
This has come up a number of times in
#pythonon IRC. I'd absolutely be happy to help etc with this if needed.