8000 Review bpo-43614: Search is not beginner friendly · Issue #44 · python/docs-community · GitHub
[go: up one dir, main page]
Skip to content
8000

Review bpo-43614: Search is not beginner friendly #44

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
iritkatriel opened this issue Apr 5, 2022 · 4 comments
Closed

Review bpo-43614: Search is not beginner friendly #44

iritkatriel opened this issue Apr 5, 2022 · 4 comments

Comments

@iritkatriel
Copy link
Member

An open issue that you may be able to resolve.
@astrojuanlu
Copy link

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

@stsewd
Copy link
stsewd commented 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
Copy link
Member

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?

@CAM-Gerlach CAM-Gerlach mentioned this issue Apr 16, 2022
Closed
@AA-Turner
Copy link
Member

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

A

@CAM-Gerlach CAM-Gerlach mentioned this issue Aug 1, 2022
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
39C7
Development

No branches or pull requests
5 participants
@astrojuanlu @iritkatriel @stsewd @AA-Turner @CAM-Gerlach
0