[issue13850] Summary tables for argparse add_argument options

[Ezio Melotti]

Ezio Melotti <ezio.melotti at gmail.com> added the comment:

> * 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

----------
stage:  -> patch review
type:  -> enhancement

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13850>
_______________________________________