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?