Repository navigation
Summary tables for argparse add_argument options #58058
Description
| BPO | 13850 |
|---|---|
| Nosy | @rhettinger, @ncoghlan, @ezio-melotti, @merwok, @bitdancer, @masklinn, @berkerpeksag, @matrixise |
| PRs | |
| Files |
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 2012-01-24.05:54:57.629>
labels = ['3.8', 'type-feature', '3.7', 'docs']
title = 'Summary tables for argparse add_argument options'
updated_at = <Date 2019-03-24.06:00:34.485>
user = 'https://github.com/ncoghlan'bugs.python.org fields:
activity = <Date 2019-03-24.06:00:34.485>
actor = 'matrixise'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2012-01-24.05:54:57.629>
creator = 'ncoghlan'
dependencies = []
files = ['25018', '38917', '38966']
hgrepos = []
issue_num = 13850
keywords = ['patch']
message_count = 22.0
messages = ['151880', '151881', '151889', '151891', '151895', '151918', '151926', '151928', '151930', '156760', '156762', '159565', '223250', '240616', '240617', '240752', '240816', '240817', '336768', '336805', '336814', '338719']
nosy_count = 12.0
nosy_names = ['rhettinger', 'ncoghlan', 'bethard', 'ezio.melotti', 'eric.araujo', 'r.david.murray', 'xmorel', 'docs@python', 'tshepang', 'berker.peksag', 'matrixise', 'ttz']
pr_nums = ['12070']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue13850'
versions = ['Python 2.7', 'Python 3.7', 'Python 3.8']Linked PRs
Metadata
Metadata
Assignees
Projects
- Status
Activity
ncoghlan commentedon Jan 24, 2012
With the current argparse docs, it's very hard to get a quick reminder of how to spell the various parameters for add_argument, and just what they do. This issue suggests adding a "Quick Reference" section for add_argument, with the following elements:
ncoghlan commentedon Jan 24, 2012
Looking at the docs, a 4th table in the quick reference section would be useful: the parameters for ArgumentParser itself.
Note that the ArgumentParser and add_arguments() parameters are already summarised in their respective entries, but there are currently no summaries at all for the possible "action" and "nargs" values
masklinn commentedon Jan 24, 2012
Creating the tables should not be too hard, especially using e.g. org-mode, but:
Where should those tables live? The argparse documentation is pretty big and there's no completely obvious place. I would guess table 1. could just replace the list of arguments in http://docs.python.org/py3k/library/argparse.html#the-add-argument-method but things are harder for
action(as many actions have examples as well, so the listing can't just be replaced) and fornargsIf the current lists of
argument: role(in ArgumentParser and add_argument) are not sufficient, why would a table somehow be considering it would add visual clutter (table borders, for instance)?Maybe a good alternative would be to build a table style for info fields lists and to use :param: wherever that belongs?
Or the doc could be split into a "quickstart" with just a listing of arguments and a *very simple* example or two, and then the exhaustive documentation, which could even be a separate document?
ncoghlan commentedon Jan 24, 2012
My specific suggestion is to have a dedicated "Quick Reference" section before the first example.
This section would be aimed at two groups of people:
Since the heart of argparse is the ability to map arguments to actions, I'd suggest the quick reference section actually lead with a table of "actions" that argparse natively supports, along with a final entry pointing to the information on custom actions (i.e. subclasses of argparse.Action).
Likely columns for this first table: Action Name, Description, Parameters
The "Parameters" column would span multiple lines, with one parameter and a brief description of the parameter on each line.
The second table could then just be a short summary of the various 'nargs' values.
Repeating the list of parameters to ArgumentParser in the quick reference section probably isn't necessary, and the short parameter descriptions in the actions table should suffice for add_argument().
masklinn commentedon Jan 24, 2012
OK, that looks like a good plan.
bethard commentedon Jan 24, 2012
Sounds like an excellent plan to me too.
masklinn commentedon Jan 24, 2012
I started looking into that, and it turns out that's more annoying than expected: a bunch of parameters are shared by many (to all) actions, leading to lots of duplications in the table. And the full matrix of actions to parameters is not really explained in the doc.
In fact, I'm coming around to thinking a matrix of the interaction between actions and arguments could be better and clearer than a table of actions with parameters bunched together at the end.
In any case, it would certainly be more maintainable... except for rST not really having support for attributes on data tables, and (as far as I can tell) can't handle horizontal headers.
ncoghlan commentedon Jan 25, 2012
Having a second table of "Applicable Parameters" could definitely work. I don't think the "no horizontal headers" limitation should be a big problem - the matrix should be readable even if the action names are just listed in an ordinary column.
rhettinger commentedon Jan 25, 2012
+1 from me. The docs in their present form are a great tutorial but are a total failure as a quick reference.
Besides having table of parameters, it may also be worthwhile to move some of the examples to a HOWTO document (much as was done with the logging package).
masklinn commentedon Mar 25, 2012
Had some time to play with this today, here's a draft matrix of actions and add_argument parameters which is pretty readable, but:
helpaction from the table as it's unlikely anyone will want to override it (and its row was completely blank)I also tried my hand at formatting
nargs, but I don't see it as much clearer than http://docs.python.org/library/argparse.html#nargs without the examples, it's still just a mapping from a value to a behavior. I think the result would be just as good if the currentnargsdescription was made into a definition list (in effect, it already is one emulated through an unordered list) and the examples were moved or removed.masklinn commentedon Mar 25, 2012
completion for list item 4:
ezio-melotti commentedon Apr 29, 2012
Indeed. Maybe this should be moved down in the page, and possibly provide a link to the top (see e.g. the unittest doc 0 and the link on top to jump to the list of assert methods). Once people know it's there they will find it easily, but opening the doc with this table is a bit confusing IMHO. Adding a couple of line to explain what the table is for might also help.
In the rst source only latin-1 chars are allowed (otherwise
make pdfbreaks), so you should replace the tick marks with something else (e.g. "x" or "yes"/"no").You can also add notes numbers just next to the "x"s and add a description below [1]. This could be applied to the "const" column as well if you want to save some horizontal space. If you want to save even more space you could remove the version row/column and add a note about it.
Maybe you could add a note about this too.
This might be useful (I did it in the assert methods' tables in the unittest doc 0), and having links in the HTML probably outweighs the fact that the rst source becomes less readable.
Note that (depending on what you change), you might be able to use the lightweight syntax for tables if you prefer.
[1]: e.g. http://docs.python.org/library/stdtypes.html#numeric-types-int-float-long-complex
7 remaining items
rhettinger commentedon Feb 28, 2019
I like the idea of having various summary tables for argparse, but the one in the PR isn't visually attractive or self-explanatory.
matrixise commentedon Feb 28, 2019
Hi @Raymond,
Yep, I understand about the "look", I have seen the result after the build of the doc but the patch was like that and I did not want to change the initial patch.
Would you suggest one layout and I could update the PR with your recommendations?
Thanks for your review
matrixise commentedon Mar 24, 2019
I close my PR, if anyone wants to submit an other PR, feel free to do it.
Merge branch 'main' into pythongh-58058
GH-58058: Add quick reference for `ArgumentParser` to argparse docs (g…
Merge branch 'main' into fix-help-double-prompt
savannahostrowski commentedon Oct 1, 2024
This is can be closed as completed now as both #124227 and #91726 have been merged.