bpo-21150: Add summary of argparse

Doc/library/argparse.rst

@@ -26,6 +26,61 @@ module also automatically generates help and usage messages and issues errors
 when users give the program invalid arguments.
 
 
+Summary
+-------
+
+Core function
+^^^^^^^^^^^^^
+
+.. csv-table::
+    :header: "Name", "Common Used Arguments", "Example"
+
+    ":class:`argparse.ArgumentParser`", "`prog`_, `description`_, `formatter_class`_", "``parser = argparse.ArgumentParser(prog='PROG', description='DESC', formatter_class=argparse.RawDescriptionHelpFormatter)``"
+    ":func:`ArgumentParser.add_argument`", "`name or flags`_, `action`_, `default`_, `type`_, `required`_, `help`_", "``parser.add_argument('-v', '--verbose', action='store_true', help='Show various debugging information')``"
+
+
+Basic Usage of :func:`add_argument`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+**Name or Flags Type**
+
+====================== ===========================
+Type                   Example
+====================== ===========================
+Positional             ``'foo'``
+Optional               ``'-v'``, ``'--verbose'``
+====================== ===========================
+
+
+**Basic Arguemnts:**
+
+====================== =============================================== =========================================================================================================================
+Name                   Description                                     Keywords
+====================== =============================================== =========================================================================================================================
+`action`_              What to do on arguments                         ``'store'``, ``'store_const'``, ``'store_true'``, ``'append'``, ``append_const``, ``count``, ``help``, ``version``
+`default`_             Default value of arguments
+`type`_                Treat arguments as type                         ``int``, ``float``, ``bool``, ``argparse.FileType('w')``, ``callable function``
+`help`_                Help message of arguments
+====================== =============================================== =========================================================================================================================
+
+
+
+**Advance Arguments:**
+
+====================== ================================================== =======================================================================================================================
+Name                   Description                                        Keywords
+====================== ================================================== =======================================================================================================================
+`nargs`_               Associates number of arguments                     ``N`` (an integer), ``'?'``, ``'*'``, ``'+'``, ``argparse.REMAINDER``
+`const`_               The constant values of name or flags
+`choices`_             Arguments should selected from this set or values  ``['foo', 'bar']``, ``range(1, 10)``, Any object that support ``in`` operator
+`required`_            Indicate a optional argument is required or not    ``True``, ``False``
+`metavar`_             A alternative display name for argument
+`dest`_                The name used in ``parse_args()``
+====================== ================================================== =======================================================================================================================
+
+
+
 Example
 -------
 
@@ -185,6 +240,8 @@ ArgumentParser objects
 The following sections describe how each of these are used.
 
 
+.. _prog:
+
 prog
 ^^^^
 
@@ -282,6 +339,8 @@ The ``%(prog)s`` format specifier is available to fill in the program name in
 your usage messages.
 
 
+.. _description:
+
 description
 ^^^^^^^^^^^
 
@@ -362,6 +421,8 @@ and one in the child) and raise an error.
    not be reflected in the child.
 
 
+.. _formatter_class:
+
 formatter_class
 ^^^^^^^^^^^^^^^
 
@@ -681,6 +742,8 @@ The add_argument() method
 The following sections describe how each of these are used.
 
 
+.. _name or flags:
+
 name or flags
 ^^^^^^^^^^^^^
 
@@ -713,6 +776,8 @@ be positional::
    PROG: error: too few arguments
 
 
+.. _action:
+
 action
 ^^^^^^
 
@@ -822,6 +887,9 @@ An example of a custom action::
 
 For more details, see :class:`Action`.
 
+
+.. _nargs:
+
 nargs
 ^^^^^
 
@@ -914,6 +982,8 @@ is determined by the action_.  Generally this means a single command-line argume
 will be consumed and a single item (not a list) will be produced.
 
 
+.. _const:
+
 const
 ^^^^^
 
@@ -937,6 +1007,8 @@ With the ``'store_const'`` and ``'append_const'`` actions, the ``const``
 keyword argument must be given.  For other actions, it defaults to ``None``.
 
 
+.. _default:
+
 default
 ^^^^^^^
 
@@ -987,6 +1059,8 @@ command-line argument was not present.::
    Namespace(foo='1')
 
 
+.. _type:
+
 type
 ^^^^
 
@@ -1049,6 +1123,8 @@ simply check against a range of values::
 See the choices_ section for more details.
 
 
+.. _choices:
+
 choices
 ^^^^^^^
 
@@ -1084,6 +1160,8 @@ value, so :class:`dict` objects, :class:`set` objects, custom containers,
 etc. are all supported.
 
 
+.. _required:
+
 required
 ^^^^^^^^
 
@@ -1110,6 +1188,8 @@ present at the command line.
     *options* to be *optional*, and thus they should be avoided when possible.
 
 
+.. _help:
+
 help
 ^^^^
 
@@ -1165,6 +1245,8 @@ setting the ``help`` value to ``argparse.SUPPRESS``::
      -h, --help  show this help message and exit
 
 
+.. _metavar:
+
 metavar
 ^^^^^^^
 
@@ -1229,6 +1311,8 @@ arguments::
     --foo bar baz
 
 
+.. _dest:
+
 dest
 ^^^^