Repository navigation
Ordering of search results in the docs could be improved #138277
Description
Activity
Prior issue: #86272
Maybe this worth first a more wide discussion on https://discuss.python.org/c/documentation/26
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.
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.
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.
This has come up a number of times in
#pythonon IRC. I'd absolutely be happy to help etc with this if needed.Reacted by adam j hartz- marked docs.python.org prioritises search horribly #86272 as a duplicate of this issue
on Jun 10, 2026
When searching for "str" in the documentation, for example, the built-in
strtype 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.
Linked PRs