[docs] [issue13850] Summary tables for argparse add_argument options

Xavier Morel report at bugs.python.org
Sun Mar 25 19:21:52 CEST 2012

Xavier Morel <xavier.morel at masklinn.net> added the comment:

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.

Added file: http://bugs.python.org/file25018/argparse-actions-matrix

Python tracker <report at bugs.python.org>

More information about the docs mailing list