You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Review bpo-43614: Search is not beginner friendly #44
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.
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:
Exact matches (list)
Subcomponent matches (ast.List)
Partial string matches (distutils.filelist)
Second, while built-in functions and classes doshow 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?
Activity
astrojuanlu commentedon Apr 5, 2022
Pinging @stsewd who knows a lot about Sphinx search and @ericholscher
stsewd commentedon Apr 5, 2022
@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 commentedon Apr 16, 2022
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
listin the Python 3.11 docs isdistutils.filelistfollowed byplistlib, which are then followed byast.List,imaplib.IMAP4.listthelistpdb command and finally thelistbuiltin class. It would seem that index terms that merely include the stringlistare actually sorted before those that are either exact matches or includelistas a subcomponet (e.g. separated by.), and exact matches are mixed in with subcomponet matches. The correct order should be:list)ast.List)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
kwargsand/(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 commentedon May 2, 2022
This is now python/cpython#87780, discussion should happen on that issue as noted in the May 2022 meeting.
A