classification
Title: Summary tables for argparse add_argument options
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.8, Python 3.7, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: berker.peksag, bethard, docs@python, eric.araujo, ezio.melotti, matrixise, ncoghlan, r.david.murray, rhettinger, tshepang, ttz, xmorel
Priority: normal Keywords: patch

Created on 2012-01-24 05:54 by ncoghlan, last changed 2019-03-24 06:00 by matrixise.

Files
File name Uploaded Description Edit
argparse-actions-matrix xmorel, 2012-03-25 17:21 matrix of actions for add_argument parameters review
argparse-actions-matrix-v2 matrixise, 2015-04-13 14:56
patch13850v0.patch ttz, 2015-04-13 21:07 first version of patch review
Pull Requests
URL Status Linked Edit
PR 12070 closed matrixise, 2019-02-27 13:51
Messages (22)
msg151880 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2012-01-24 05:54
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:

1. Summary table with a one line description of each parameter
2. Summary table with a one line description of each alternative for the "action" parameter (including noting which other parameters are potentially relevant, such as 'choices' and 'metavar' for 'store' and 'const' for 'store_const')
3. Summary table with a one line description of each alternative for the "nargs" parameter
msg151881 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2012-01-24 06:09
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
msg151889 - (view) Author: Xavier Morel (xmorel) * Date: 2012-01-24 10:00
Creating the tables should not be too hard, especially using e.g. org-mode, but:

1. 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 for `nargs`

2. If 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?
msg151891 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2012-01-24 10:40
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:
- those wanting a quick overview of the features argparse offers them ("This looks complicated, what can it do for me?")
- those wanting a reminder of the exact spelling of various items ("I know what I want to do, and I know argparse can do it because I've done it before, but how do I tell argparse exactly what I want?")

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().
msg151895 - (view) Author: Xavier Morel (xmorel) * Date: 2012-01-24 11:42
> My specific suggestion is to have a dedicated "Quick Reference" section before the first example.

OK, that looks like a good plan.
msg151918 - (view) Author: Steven Bethard (bethard) * (Python committer) Date: 2012-01-24 17:12
Sounds like an excellent plan to me too.
msg151926 - (view) Author: Xavier Morel (xmorel) * Date: 2012-01-24 20:20
> The "Parameters" column would span multiple lines, with one parameter and a brief description of the parameter on each line.

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.
msg151928 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2012-01-25 01:18
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.
msg151930 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2012-01-25 02:20
+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).
msg156760 - (view) Author: Xavier Morel (xmorel) * Date: 2012-03-25 17:21
Had some time to play with this today, here's a draft matrix of actions and add_argument parameters which is pretty readable, but:

* It's incredibly not helpful for people who don't know argparse
* I tried adding effects descriptions in the cells instead of mere tick marks, the table becomes completely unreadable. I added a note directive below the table but it only lists a few really important/weird things, and it really won't scale beyond the current 3 items (which might already be too much)
* I completely removed the ``help`` action from the table as it's unlikely anyone will want to override it (and its row was completely blank)
* Hyperlinking and cross-linking (to the params, the actions, footnotes) would probably be a good idea, although it would definitely make the "raw text" (in-rst) 

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 current ``nargs`` description was made into a definition list (in effect, it already is one emulated through an unordered list) and the examples were moved or removed.
msg156762 - (view) Author: Xavier Morel (xmorel) * Date: 2012-03-25 17:23
completion for list item 4:

> although it would definitely make the "raw text" (in-rst) much harder to read compared to the current table (which can be used from the rst source without compiling)
msg159565 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-04-29 02:38
> * It's incredibly not helpful for people who don't know argparse

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.

> * I tried adding effects descriptions in the cells instead of mere
> tick marks, the table becomes completely unreadable.

In the rst source only latin-1 chars are allowed (otherwise `make pdf` breaks), so you should replace the tick marks with something else (e.g. "x" or "yes"/"no").

> I added a note directive below the table but it only lists a few 
> really important/weird things, and it really won't scale beyond the
> current 3 items (which might already be too much)

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.

> * I completely removed the ``help`` action from the table as it's 
> unlikely anyone will want to override it (and its row was completely blank)

Maybe you could add a note about this too.

> * Hyperlinking and cross-linking (to the params, the actions,
> footnotes) would probably be a good idea, although it would
> definitely make the "raw text" (in-rst) 

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.

[0]: http://docs.python.org/library/unittest.html
[1]: e.g. http://docs.python.org/library/stdtypes.html#numeric-types-int-float-long-complex
msg223250 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2014-07-16 18:48
At a quick glance the patch looks okay to me so as there's been a lot of positive comments can we have a formal patch review please.
msg240616 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2015-04-13 14:56
Just updated this patch with "x" instead of the unicode character.
msg240617 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2015-04-13 15:07
On 13 Apr 2015, at 10:56, Stéphane Wirtel wrote:

> Stéphane Wirtel added the comment:
>
> Just updated this patch with "x" instead of the unicode character.

Sorry bad patch, I have read the last comment (“replace by x or 
“yes/no”) and not the other comments.
msg240752 - (view) Author: Tina Zhang (ttz) Date: 2015-04-13 21:07
Created Quick Reference table subsection under the add_argument() method section - used the table originally created by xmorel, replacing ticks with 'x' and adding links to the sections in the documentation for each parameter names.  Removed the 'version' column and row as that wasn't adding much info.  

There is also a link to the quick reference subsection at the top of the page.
msg240816 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-04-14 00:38
I think it would be better to move the summary table to the end (just before the Action section), and add another link to the summary to the sentence "The following sections describe how each of these are used."  That is, follow that sentence with something like 'a summary table of the relevance of each paramter to the various possible actions is given at the end of the section', with a link on summary table.

Otherwise, the patch looks good to me.
msg240817 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2015-04-14 00:41
Hi all,

If you think the patch is ok, please merge it, we will close this issue.

Thanks
msg336768 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2019-02-27 15:55
just for 2.7, 3.7 & 3.8 because they are in bugfix mode.
msg336805 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-02-28 06:37
I like the idea of having various summary tables for argparse, but the one in the PR isn't visually attractive or self-explanatory.
msg336814 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2019-02-28 08:15
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
msg338719 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2019-03-24 06:00
I close my PR, if anyone wants to submit an other PR, feel free to do it.
History
Date User Action Args
2019-03-24 06:00:34matrixisesetmessages: + msg338719
2019-02-28 08:15:59matrixisesetmessages: + msg336814
2019-02-28 06:37:19rhettingersetmessages: + msg336805
2019-02-27 15:55:39matrixisesetmessages: + msg336768
versions: + Python 3.7, Python 3.8, - Python 3.4, Python 3.5
2019-02-27 13:51:30matrixisesetpull_requests: + pull_request12090
2019-02-24 22:56:09BreamoreBoysetnosy: - BreamoreBoy
2015-04-14 00:41:04matrixisesetmessages: + msg240817
2015-04-14 00:38:47r.david.murraysetnosy: + r.david.murray
messages: + msg240816
2015-04-13 21:07:23ttzsetfiles: + patch13850v0.patch

nosy: + ttz
messages: + msg240752

keywords: + patch
2015-04-13 15:07:58matrixisesetmessages: + msg240617
2015-04-13 14:56:14matrixisesetfiles: + argparse-actions-matrix-v2
nosy: + matrixise
messages: + msg240616

2014-07-16 20:39:58berker.peksagsetnosy: + berker.peksag
2014-07-16 18:48:44BreamoreBoysetnosy: + BreamoreBoy

messages: + msg223250
versions: + Python 3.4, Python 3.5, - Python 3.2, Python 3.3
2012-04-29 02:38:35ezio.melottisettype: enhancement
messages: + msg159565
stage: patch review
2012-03-25 17:23:41xmorelsetmessages: + msg156762
2012-03-25 17:21:51xmorelsetfiles: + argparse-actions-matrix

messages: + msg156760
2012-03-18 21:56:51tshepangsetnosy: + tshepang
2012-02-03 13:41:39eric.araujosetnosy: + eric.araujo
2012-01-25 02:20:04rhettingersetnosy: + rhettinger
messages: + msg151930
2012-01-25 01:18:34ncoghlansetmessages: + msg151928
2012-01-24 20:20:56xmorelsetmessages: + msg151926
2012-01-24 17:12:08bethardsetmessages: + msg151918
2012-01-24 11:42:54xmorelsetmessages: + msg151895
2012-01-24 10:40:44ezio.melottisetnosy: + ezio.melotti
2012-01-24 10:40:13ncoghlansetmessages: + msg151891
2012-01-24 10:00:21xmorelsetnosy: + xmorel
messages: + msg151889
2012-01-24 06:09:59ncoghlansetmessages: + msg151881
2012-01-24 05:54:57ncoghlancreate