Open 1badd512-0525-4080-8712-5291bd4c7493 opened 3 years ago
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
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.
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 ?)
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.
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:
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.
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: +
, **
, """
.
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:
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 entrycls
isn't mentioned anywhere at all, so it would have to be a new entryIt 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 :tada:
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: ```python assignee = None closed_at = None created_at =
labels = ['type-feature', '3.8', '3.9', '3.10', 'docs']
title = 'Search is not beginner friendly'
updated_at =
user = 'https://github.com/TonyFlury'
```
bugs.python.org fields:
```python
activity =
actor = 'ammar2'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation =
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']
```