bpo-21150: Add quick link/summary table to the top of argparse documentation (GH...

No work has been done to move this forward.  On the theory that perfect is the enemy of good, I'm going to push it and we can make minor edits as needed afterwards.

diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index e050d6298b6ff6507ee31d6f44164b0fa61bb4c8..425409db3cb751f2dd09709b4b71c91613d79a6c 100644 (file)
--- a/Doc/library/argparse.rst
+++ b/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
 -------
 
@@ -196,6 +265,8 @@ ArgumentParser objects
 The following sections describe how each of these are used.
 
 
+.. _prog:
+
 prog
 ^^^^
 
@@ -293,6 +364,8 @@ The ``%(prog)s`` format specifier is available to fill in the program name in
 your usage messages.
 
 
+.. _description:
+
 description
 ^^^^^^^^^^^
 
@@ -373,6 +446,8 @@ and one in the child) and raise an error.
    not be reflected in the child.
 
 
+.. _formatter_class:
+
 formatter_class
 ^^^^^^^^^^^^^^^
 
@@ -716,6 +791,8 @@ The add_argument() method
 The following sections describe how each of these are used.
 
 
+.. _name_or_flags:
+
 name or flags
 ^^^^^^^^^^^^^
 
@@ -749,6 +826,8 @@ be positional::
    PROG: error: the following arguments are required: bar
 
 
+.. _action:
+
 action
 ^^^^^^
 
@@ -884,6 +963,9 @@ An example of a custom action::
 
 For more details, see :class:`Action`.
 
+
+.. _nargs:
+
 nargs
 ^^^^^
 
@@ -971,6 +1053,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
 ^^^^^
 
@@ -997,6 +1081,8 @@ the various :class:`ArgumentParser` actions.  The two most common uses of it are
    ``const=None`` by default, including when ``action='append_const'`` or
    ``action='store_const'``.
 
+.. _default:
+
 default
 ^^^^^^^
 
@@ -1055,6 +1141,8 @@ command-line argument was not present::
    Namespace(foo='1')
 
 
+.. _type:
+
 type
 ^^^^
 
@@ -1124,6 +1212,8 @@ For type checkers that simply check against a fixed set of values, consider
 using the choices_ keyword instead.
 
 
+.. _choices:
+
 choices
 ^^^^^^^
 
@@ -1166,6 +1256,8 @@ from *dest*.  This is usually what you want because the user never sees the
 many choices), just specify an explicit metavar_.
 
 
+.. _required:
+
 required
 ^^^^^^^^
 
@@ -1192,6 +1284,8 @@ present at the command line.
     *options* to be *optional*, and thus they should be avoided when possible.
 
 
+.. _help:
+
 help
 ^^^^
 
@@ -1247,6 +1341,8 @@ setting the ``help`` value to ``argparse.SUPPRESS``::
      -h, --help  show this help message and exit
 
 
+.. _metavar:
+
 metavar
 ^^^^^^^
 
@@ -1311,6 +1407,8 @@ arguments::
     --foo bar baz
 
 
+.. _dest:
+
 dest
 ^^^^
 

diff --git a/Misc/NEWS.d/next/Documentation/2019-02-24-03-06-59.bpo-21150.Vqv8Yc.rst b/Misc/NEWS.d/next/Documentation/2019-02-24-03-06-59.bpo-21150.Vqv8Yc.rst
new file mode 100644 (file)
index 0000000..d1b5615
--- /dev/null
+++ b/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.
\ No newline at end of file