8000 Search is not beginner friendly · Issue #87780 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

Search is not beginner friendly #87780

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
TonyFlury mannequin opened this issue Mar 24, 2021 · 7 comments
Open

Search is not beginner friendly #87780

TonyFlury mannequin opened this issue Mar 24, 2021 · 7 comments
Labels
3.9 only security fixes 3.10 only security fixes 3.11 only security fixes docs Documentation in the Doc dir type-feature A feature request or enhancement

Comments

@TonyFlury
Copy link
Mannequin
TonyFlury mannequin commented Mar 24, 2021
BPO 43614
Nosy @rhettinger, @Rosuav, @serhiy-storchaka, @ammaraskar, @TonyFlury, @kamilturek
PRs
  • bpo-43433: Reattach query parameters after parsing URI #25045
    		•

    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 2021-03-24.11:12:48.698>
labels = ['type-feature', '3.8', '3.9', '3.10', 'docs']
title = 'Search is not beginner friendly'
updated_at = <Date 2021-04-29.16:24:39.303>
user = 'https://github.com/TonyFlury'

    bugs.python.org fields:

    activity = <Date 2021-04-29.16:24:39.303>
actor = 'ammar2'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2021-03-24.11:12:48.698>
creator = 'anthony-flury'
dependencies = []
files = []
hgrepos = []
issue_num = 43614
keywords = ['patch']
message_count = 4.0
messages = ['389442', '389473', '389627', '392328']
nosy_count = 7.0
nosy_names = ['rhettinger', 'docs@python', 'Rosuav', 'serhiy.storchaka', 'ammar2', 'anthony-flury', 'kamilturek']
pr_nums = ['25045']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue43614'
versions = ['Python 3.8', 'Python 3.9', 'Python 3.10']
    @TonyFlury
    Copy link
    Mannequin Author
    TonyFlury mannequin commented Mar 24, 2021

    A commonly asked question on Quora is 'What do *args and **kwargs' mean ?

    While it is relatively easy for community to answer these questions the search tool on the standard documentation doesn't make it easy.

    I understand that 'args' and 'kwargs' are both naming conventions, they are very common across the documentation, but searching on '*args' or '**kwargs' doesn't actually find anything useful - it certainly doesn't place 'https://docs.python.org/3/tutorial/controlflow.html#arbitrary-argument-lists' at or close to the top of the list.

    It is my view that the documentation should be beginner friendly, but in this case (and many other I guess) you have to know what to search for to find something useful.

    I note that even common phrases in Computing (such as 'variable arguments' or 'variable parameters') don't find anything useful. The term 'variadic' does find the relevant page, but the link displayed in the search results lands on the page (but not the relevant section) - and many beginners wont search for 'variadic'.

    The index and search need to be improved to help beginners - specifically in this case

    • Search Index should include common conventional names (such as args, kwargs)
    • Search Index should include common computing terms ('variable arguments' for example - even if the documentation doesn't actually use that terminology).
    • Search should link to the relevant section (and not just the page).

    @TonyFlury TonyFlury mannequin added the 3.9 only security fixes label Mar 24, 2021
    @TonyFlury TonyFlury mannequin assigned docspython Mar 24, 2021
    @TonyFlury TonyFlury mannequin added docs Documentation in the Doc dir 3.9 only security fixes labels Mar 24, 2021
    @TonyFlury TonyFlury mannequin assigned docspython Mar 24, 2021
    @TonyFlury TonyFlury mannequin added the docs Documentation in the Doc dir label Mar 24, 2021
    @serhiy-storchaka
    Copy link
    Member

    Ha! I just was going to open the same issue (perhaps we read the same post on Quora).

    I concur that it is perhaps worth to add index entries for common parameter names (args, kwargs, self, cls) and also for *args and **kwargs and add notions that such name is commonly used for such parameter.

    @serhiy-storchaka serhiy-storchaka added 3.8 (EOL) end of life 3.10 only security fixes type-feature A feature request or enhancement labels Mar 24, 2021
    @TonyFlury
    Copy link
    Mannequin Author
    TonyFlury mannequin commented Mar 28, 2021

    Is PR 25045 the correct Pull request - this Issue is a documentation change - the linked PR is related to bpo-43433 (a change to xmlrpc.client ?)

    @ammaraskar
    Copy link
    Member

    Just a little update to this, now that bpo-34398 is fixed it is possible to make this more beginner friendly by making sure the right terms have glossary entries.

    As an example, here is a search for "argument" on the latest docs:

    https://docs.python.org/3.10/search.html?q=argument

    It would be nice if kwargs/args could also point to that.

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    @AA-Turner AA-Turner mentioned this issue May 2, 2022
    Closed
    @hugovk hugovk added 3.11 only security fixes and removed 3.8 (EOL) end of life labels May 3, 2022
    @CAM-Gerlach CAM-Gerlach mentioned this issue Aug 1, 2022
    Open
    @CAM-Gerlach
    Copy link
    Member
    CAM-Gerlach commented Aug 1, 2022 •
    edited
    Loading

    Related: #60075 and #89541

    If this just involves adding glossary entries for some common terms, I can try to take a look at this soon-ish, since this is high-impact but should be fairly straightforward to accomplish.

    We should compile a list of relevant entries to add. Here are those mentioned here:

    • args
    • kwargs
    • self
    • cls
    • dunder?
    • walrus (operator)?

    I'm there there are others; one thing I believe Guido mentioned elsewhere was * and / in signatures, though I'll have to see if they'll actually work as glossary entries.

    @CAM-Gerlach CAM-Gerlach mentioned this issue Aug 1, 2022
    Closed
    @serhiy-storchaka
    Copy link
    Member

    No, I do not think that we need glossary entries for these words. There are already entries for var-positional and var-keyword parameters. We need to make search for args and kwargs finding these entries.

    It would be nice if search work for Python operators and other syntax elements that are present in the index: +, **, """.

    @CAM-Gerlach
    Copy link
    Member
    CAM-Gerlach commented Aug 3, 2022 •
    edited
    Loading

    No, I do not think that we need glossary entries for these words. There are already entries for var-positional and var-keyword parameters. We need to make search for args and kwargs finding these entries.

    Ah, good point, thanks—we wouldn't want to duplicate that then, just make it easier to find, since the peculiar terms "var-positional" and "var-keyword" for these aren't used anywhere else I could find in the docs, nor in general usage (such that I missed them myself).

    While we could just add stub terms that point back to the main term as is done for positional and keyword argument, this requires readers to jump an extra step, and still doesn't point to the specific part of the parameter entry it refers to (which is the longest in the glossary and takes up a full screen when searching), which may lead to confusion and ambiguity. Likewise, we could just add multiple terms to the same existing entry, but this would overload the term list and doesn't fix the main problems (length and ambiguity).

    Instead, we should split the bullets for positional-only, keyword-only, positional variadic and keyword variadic parameters into their own entries that have their respective aliases as additional terms, and cross-linking the main entry to the sub-entries and vice versa. Then, searching for kwargs, *args or keyword-only argument will resolve to the specific term and display just the relevant text, while searching for parameter won't display a wall of text in the results. We will need to fix the custom glossary search code to properly handle multi-term entries as it should, but that should be doable. I can open a PR once I get one merged to fix another issue with the same code in #90492 .

    That does leave self and cls, and potentially others, unresolved:

    • Method does mention self, but I'm not sure it makes sense as a (visible) alias and there currently isn't a way I know of to make an invisible one, so it would have to be a separate entry
    • cls isn't mentioned anywhere at all, so it would have to be a new entry

    It would be nice if search work for Python operators and other syntax elements that are present in the index: +, **, """.

    See sphinx-doc/sphinx#6692 ; @AA-Turner is working on it for Sphinx 5.2.0 🎉

    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Assignees
    No one assigned
    Labels
    3.9 only security fixes 3.10 only security fixes 3.11 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
    4 participants
    @ammaraskar @hugovk @serhiy-storchaka @CAM-Gerlach
    0