Review bpo-43614: Search is not beginner friendly

[iritkatriel]

An open issue that you may be able to resolve.

[astrojuanlu]

Pinging @stsewd who knows a lot about Sphinx search and @ericholscher

[stsewd]

@astrojuanlu hey!

What I know is about the search integration we have on Read the Docs (https://docs.readthedocs.io/en/stable/server-side-search.html). docs.python.org/ isn't hosted on rtd. But the solution mentioned on the issue about using the glossary entries should work.

[CAM-Gerlach]

Seems like these same issues were also brought up in #39 , I'd suggest either closing this one or that one as a duplicate

Per our testing and discussion at the meeting, there were a few likely-solvable specific issues we identified:

• Results from the index are not ordered sensibly, with exact or exact-subpart matches being ordered after index entries that merely have the search term as part of their names. For example, the top hit in a search for list in the Python 3.11 docs is distutils.filelist followed by plistlib, which are then followed by ast.List, imaplib.IMAP4.list the list pdb command and finally the list builtin class. It would seem that index terms that merely include the string list are actually sorted before those that are either exact matches or include list as a subcomponet (e.g. separated by .), and exact matches are mixed in with subcomponet matches. The correct order should be:

  1. Exact matches (list)
  2. Subcomponent matches (ast.List)
  3. Partial string matches (distutils.filelist)

• Second, while built-in functions and classes do show up in searches of the Python 3.11 docs, they are inexplicably absent in the docs for the current latest released version, Python 3.10 and all previous stable versions I tested (back to 3.5) in the current stable version and all previous versions I tested (back to 3.5). Was this fixed on purpose, or by accident? Can it be backported to previous versions' docs, since it seems like a pretty clear bug for the builtin classes and functions, of all things, to be completely missing from the search?

• Third, as most directly addressed by the linked issue, there appeared to be a desire to have specific terms like kwargs and / (for positional-only args) included in the search index, as currently searching for them either in the docs or via an external search engine does not return any useful results. Maybe the easiest way to do this would be to add them to the Glossary, which gets prominently linked at the top of the search results, and then add a brief summary and links to further information there?

[AA-Turner]

This is now python/cpython#87780, discussion should happen on that issue as noted in the May 2022 meeting.

A