bpo-21150: add quick link/summary table to the top of argparse documentation

Doc/library/argparse.rst

@@ -26,6 +26,75 @@ module also automatically generates help and usage messages and issues errors
 when users give the program invalid arguments.
 
 
+Summary
+-------
+
+Core Functionality
+^^^^^^^^^^^^^^^^^^
+
+The :mod:`argparse` module's support for command-line interfaces is built
+from the following:
+
+The :class:`argparse.ArgumentParser` creates a new :class:`ArgumentParser`
+object. Commonly used arguments include prog_, description_, and
+formatter_class_. For example, the user can create an instance of
+:class:`ArgumentParser` through the following::
+
+   >>> parser = argparse.ArgumentParser(prog='PROG', description='DESC',
+   ...                                  formatter_class=argparse.RawDescriptionHelpFormatter)
+
+The :func:`ArgumentParser.add_argument` is a function that is used
+to define how a single command-line argument should be parsed. Commonly used
+arguments include `name or flags`_, action_, default_, type_, required_,
+and help_. An example of the function :func:`ArgumentParser.add_argument`
+is as follows::
+
+   >>> 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 Arguments:**
+
+====================== =========================================================== =========================================================================================================================
+Name                   Description                                                 Keywords
+====================== =========================================================== =========================================================================================================================
+action_                Specifies how an argument should be handled                 ``'store'``, ``'store_const'``, ``'store_true'``, ``'append'``, ``'append_const'``, ``'count'``, ``'help'``, ``'version'``
+default_               Default value used when an argument is not provided
+type_                  Automatically converts an argument to the given type        :class:`int`, :class:`float`, :class:`bool`, ``argparse.FileType('w')``, ``callable function``
+help_                  Help message of an argument
+====================== =========================================================== =========================================================================================================================
+
+
+
+**Advanced Arguments:**
+
+====================== =========================================================== =======================================================================================================================
+Name                   Description                                                 Keywords
+====================== =========================================================== =======================================================================================================================
+nargs_                 Associates a single action with the number of arguments     ``N`` (:class:`int`), ``'?'``, ``'*'``, ``'+'``, ``argparse.REMAINDER``
+const_                 Stores constant values of names or flags
+choices_               A container that lists the possible values                  ``['foo', 'bar']``, ``range(1, 10)``, Any object that supports ``in`` operator
+required_              Indicates if an optional argument is required or not        ``True``, ``False``
+metavar_               An alternative display name for the argument
+dest_                  Specifies name of attribute to be used in ``parse_args()``
+====================== =========================================================== =======================================================================================================================
+
+
+
 Example
 -------
 
@@ -185,6 +254,8 @@ ArgumentParser objects
 The following sections describe how each of these are used.
 
 
+.. _prog:
+
 prog
 ^^^^
 
@@ -282,6 +353,8 @@ The ``%(prog)s`` format specifier is available to fill in the program name in
 your usage messages.
 
 
+.. _description:
+
 description
 ^^^^^^^^^^^
 
@@ -362,6 +435,8 @@ and one in the child) and raise an error.
    not be reflected in the child.
 
 
+.. _formatter_class:
+
 formatter_class
 ^^^^^^^^^^^^^^^
 
@@ -683,6 +758,8 @@ The add_argument() method
 The following sections describe how each of these are used.
 
 
+.. _name_or_flags:
+
 name or flags
 ^^^^^^^^^^^^^
 
@@ -715,6 +792,8 @@ be positional::
    PROG: error: the following arguments are required: bar
 
 
+.. _action:
+
 action
 ^^^^^^
 
@@ -824,6 +903,9 @@ An example of a custom action::
 
 For more details, see :class:`Action`.
 
+
+.. _nargs:
+
 nargs
 ^^^^^
 
@@ -924,6 +1006,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
 ^^^^^
 
@@ -947,6 +1031,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
 ^^^^^^^
 
@@ -997,6 +1083,8 @@ command-line argument was not present::
    Namespace(foo='1')
 
 
+.. _type:
+
 type
 ^^^^
 
@@ -1059,6 +1147,8 @@ simply check against a range of values::
 See the choices_ section for more details.
 
 
+.. _choices:
+
 choices
 ^^^^^^^
 
@@ -1094,6 +1184,8 @@ value, so :class:`dict` objects, :class:`set` objects, custom containers,
 etc. are all supported.
 
 
+.. _required:
+
 required
 ^^^^^^^^
 
@@ -1120,6 +1212,8 @@ present at the command line.
     *options* to be *optional*, and thus they should be avoided when possible.
 
 
+.. _help:
+
 help
 ^^^^
 
@@ -1175,6 +1269,8 @@ setting the ``help`` value to ``argparse.SUPPRESS``::
      -h, --help  show this help message and exit
 
 
+.. _metavar:
+
 metavar
 ^^^^^^^
 
@@ -1239,6 +1335,8 @@ arguments::
     --foo bar baz
 
 
+.. _dest:
+
 dest
 ^^^^
 

Misc/NEWS.d/next/Documentation/2019-02-24-03-06-59.bpo-21150.Vqv8Yc.rst

@@ -0,0 +1 @@
+Place summary/quick links table at the top of the documentation for the argparse module to benefit ease of use.