8000 docs.python.org prioritises search horribly · Issue #86272 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

docs.python.org prioritises search horribly #86272

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
Open
masklinn mannequin opened this issue Oct 21, 2020 · 4 comments
Open

docs.python.org prioritises search horribly #86272

masklinn mannequin opened this issue Oct 21, 2020 · 4 comments
Labels
3.7 (EOL) end of life 3.8 (EOL) end of life 3.9 only security fixes docs Documentation in the Doc dir type-feature A feature request or enhancement

Comments

@masklinn
Copy link
Mannequin
masklinn mannequin commented Oct 21, 2020
BPO 42106
Nosy @methane, @masklinn

Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2020-10-21.09:59:57.032>
labels = ['3.8', 'type-feature', '3.7', '3.9', 'docs']
title = 'docs.python.org prioritises search horribly'
updated_at = <Date 2020-10-21.13:36:39.556>
user = 'https://github.com/masklinn'

bugs.python.org fields:

activity = <Date 2020-10-21.13:36:39.556>
actor = 'xmorel'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2020-10-21.09:59:57.032>
creator = 'xmorel'
dependencies = []
files = []
hgrepos = []
issue_num = 42106
keywords = []
message_count = 3.0
messages = ['379203', '379206', '379207']
nosy_count = 3.0
nosy_names = ['methane', 'xmorel', 'docs@python']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue42106'
versions = ['Python 3.6', 'Python 3.7', 'Python 3.8', 'Python 3.9']
@masklinn
Copy link
Mannequin Author
masklinn mannequin commented Oct 21, 2020

I expect it simply uses sphinx and I don't know if sphinx's search is easily customisable but the experience is really terrible when looking for the doc of a specific thing, *especially* when that thing is or is related to a builtin, which I'd expect to be extremely common. Though I expect part of the issue might also be that builtin or ABC methods are not documented *as such*, they're just written as code in tables.

For instance if you search "append": https://docs.python.org/3/search.html?q=append

On my end, neither list nor MutableSequence appear anywhere on this page, even scrolling down.

Searching for "list": https://docs.python.org/3/search.html?q=list

The documentation for the builtin "list" object also doesn't appear on the page. "Data Structures"[0] and "built-in types"[1] appear below the fold and the former is genuinely useful but also very easy to miss (I had not actually noticed it before going back in order to get the various links and try to extensively describe the issue). Neither actually links to the list builtin type though.

Above the fold we find various "list" methods and classes from the stdlib as well as the PDB list comment, none of which seems like the best match for the query.

And even Google doesn't help much there, most of the hits are for third-party documentation, and the one docs.python.org link is to the Data Structures page *of Python 2.7*.

[0] https://docs.python.org/3/tutorial/datastructures.html?highlight=list
[1] https://docs.python.org/3/library/stdtypes.html?highlight=list

8000
@masklinn masklinn mannequin added 3.7 (EOL) end of life 3.8 (EOL) end of life 3.9 only security fixes labels Oct 21, 2020
@masklinn masklinn mannequin assigned docspython Oct 21, 2020
@masklinn masklinn mannequin added docs Documentation in the Doc dir type-feature A feature request or enhancement 3.7 (EOL) end of life 3.8 (EOL) end of life 3.9 only security fixes labels Oct 21, 2020
@masklinn masklinn mannequin assigned docspython Oct 21, 2020
@masklinn masklinn mannequin added docs Documentation in the Doc dir type-feature A feature request or enhancement labels Oct 21, 2020
@methane
Copy link
Member
methane commented Oct 21, 2020

Can we add search box using DuckDuckGo?
https://duckduckgo.com/?q=site%3Adocs.python.org%2F3%2F+list+append

@masklinn
Copy link
Mannequin Author
masklinn mannequin commented Oct 21, 2020

Apparently it's at least a possibility on DDG's side (https://duckduckgo.com/search_box), don't know how easy it'd be to integrate in sphinx, or whether a hard dependency on an external search engine is acceptable / desirable.

@ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
@CAM-Gerlach
Copy link
Member

To note, there have been significant improvements here; with recent Sphinx versions, the Python 3.11+ docs do show builtin functions and classes near the top of the search, and the docs also now have custom functionality that displays glossary entries highlighted at the top, for which there's one for List as well.

This is closely related to #89541 and #60075 , which cover mostly similar ground so I was going to close it as a duplicate, but this issue brings up a unique point—even in the latest 3.12 docs, append still doesn't show up (at least as a method of either List or MutableSequence), and indeed, none of the MutableSequence methods do, nor do the two methods (index and count) in the common sequence operations section on lists, tuples, etc. In fact, they aren't able to be directly referenced at all, either through internal or external links, since they are just rows in a table.

While including index entries in the search (as they are indexed) would mostly solve the search discoverability problem, this is an upstream Sphinx issue ( sphinx-doc/sphinx#6692 ) and would need to be fixed there. Even if and when it is, it still means that these are not independently reference-able objects, and do not follow the standard, expected and easy to follow structure for describing the methods of a class, including those of most of the other collections documented on the same page.

Therefore, it would seem to make sense to just solve the root issue by converting the method items currently listed in the mutable sequence operations table to actual method entities under an appropriate class.

Ideally, they would be under the MutableSequence class on the collections.abc page (which would be linked under the list class, as the methods apply to all MutableSequence objects and would allow cross-referencing them elsewhere as such. However, the other existing collection types on the latter page have their methods enumerated under the classes on that page whereas none of the collection.abcs do, so it wouldn't make sense to do this for list/tuple and not the rest (which is out of scope here, and could be considered separately later). Therefore, they can just be added under list (and tuple) for now, which is also more searchable.

@CAM-Gerlach CAM-Gerlach mentioned this issue Aug 3, 2022
Closed
@CAM-Gerlach CAM-Gerlach mentioned this issue Oct 13, 2022
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
3.7 (EOL) end of life 3.8 (EOL) end of life 3.9 only security fixes docs Documentation in the Doc dir type-feature A feature request or enhancement
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@methane @CAM-Gerlach
0