gh-84116: Docs: Document help and aliases for argparse.add_parser()

Doc/library/argparse.rst

@@ -1700,20 +1700,20 @@ The Namespace object
 Other utilities
 ---------------
 
-Subcommands
+Sub-commands
 ^^^^^^^^^^^^
 
 .. method:: ArgumentParser.add_subparsers(*, [title], [description], [prog], \
                                           [parser_class], [action], \
                                           [dest], [required], \
                                           [help], [metavar])
 
-   Many programs split up their functionality into a number of subcommands,
-   for example, the ``svn`` program can invoke subcommands like ``svn
+   Many programs split up their functionality into a number of sub-commands,
+   for example, the ``svn`` program can invoke sub-commands like ``svn
    checkout``, ``svn update``, and ``svn commit``.  Splitting up functionality
    this way can be a particularly good idea when a program performs several
    different functions which require different kinds of command-line arguments.
-   :class:`ArgumentParser` supports the creation of such subcommands with the
+   :class:`ArgumentParser` supports the creation of such sub-commands with the
    :meth:`!add_subparsers` method.  The :meth:`!add_subparsers` method is normally
    called with no arguments and returns a special action object.  This object
    has a single method, :meth:`~_SubParsersAction.add_parser`, which takes a
@@ -1723,32 +1723,32 @@ Subcommands
    Description of parameters:
 
    * *title* - title for the sub-parser group in help output; by default
-     "subcommands" if description is provided, otherwise uses title for
-     positional arguments
+      "subcommands" if description is provided, otherwise uses title for
+      positional arguments
 
    * *description* - description for the sub-parser group in help output, by
-     default ``None``
+      default ``None``
 
    * *prog* - usage information that will be displayed with subcommand help,
-     by default the name of the program and any positional arguments before the
-     subparser argument
+      by default the name of the program and any positional arguments before the
+      subparser argument
 
    * *parser_class* - class which will be used to create sub-parser instances, by
-     default the class of the current parser (e.g. :class:`ArgumentParser`)
+      default the class of the current parser (e.g. :class:`ArgumentParser`)
 
    * action_ - the basic type of action to be taken when this argument is
-     encountered at the command line
+      encountered at the command line
 
    * dest_ - name of the attribute under which subcommand name will be
-     stored; by default ``None`` and no value is stored
+      stored; by default ``None`` and no value is stored
 
    * required_ - Whether or not a subcommand must be provided, by default
-     ``False`` (added in 3.7)
+      ``False`` (added in 3.7)
 
    * help_ - help for sub-parser group in help output, by default ``None``
 
    * metavar_ - string presenting available subcommands in help; by default it
-     is ``None`` and presents subcommands in form {cmd1, cmd2, ..}
+      is ``None`` and presents subcommands in form {cmd1, cmd2, ..}
 
    Some example usage::
 
@@ -1771,7 +1771,7 @@ Subcommands
      >>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])
      Namespace(baz='Z', foo=True)
 
-   Note that the object returned by :meth:`parse_args` will only contain
+   Note that the object returned by :meth:`~ArgumentParser.parse_args` will only contain
    attributes for the main parser and the subparser that was selected by the
    command line (and not any other subparsers).  So in the example above, when
    the ``a`` command is specified, only the ``foo`` and ``bar`` attributes are
@@ -1814,7 +1814,7 @@ Subcommands
        -h, --help     show this help message and exit
        --baz {X,Y,Z}  baz help
 
-   The :meth:`add_subparsers` method also supports ``title`` and ``description``
+   The :meth:`~ArgumentParser.add_subparsers` method also supports ``title`` and ``description``
    keyword arguments.  When either is present, the subparser's commands will
    appear in their own group in the help output.  For example::
 
@@ -1835,34 +1835,8 @@ Subcommands
 
        {foo,bar}   additional help
 
-   Furthermore, :meth:`~_SubParsersAction.add_parser` supports an additional
-   *aliases* argument,
-   which allows multiple strings to refer to the same subparser. This example,
-   like ``svn``, aliases ``co`` as a shorthand for ``checkout``::
-
-     >>> parser = argparse.ArgumentParser()
-     >>> subparsers = parser.add_subparsers()
-     >>> checkout = subparsers.add_parser('checkout', aliases=['co'])
-     >>> checkout.add_argument('foo')
-     >>> parser.parse_args(['co', 'bar'])
-     Namespace(foo='bar')
-
-   :meth:`~_SubParsersAction.add_parser` supports also an additional
-   *deprecated* argument, which allows to deprecate the subparser.
-
-      >>> import argparse
-      >>> parser = argparse.ArgumentParser(prog='chicken.py')
-      >>> subparsers = parser.add_subparsers()
-      >>> run = subparsers.add_parser('run')
-      >>> fly = subparsers.add_parser('fly', deprecated=True)
-      >>> parser.parse_args(['fly'])  # doctest: +SKIP
-      chicken.py: warning: command 'fly' is deprecated
-      Namespace()
-
-   .. versionadded:: 3.13
-
    One particularly effective way of handling subcommands is to combine the use
-   of the :meth:`add_subparsers` method with calls to :meth:`set_defaults` so
+   of the :meth:`~ArgumentParser.add_subparsers` method with calls to :meth:`~ArgumentParser.set_defaults` so
    that each subparser knows which Python function it should execute.  For
    example::
 
@@ -1898,12 +1872,12 @@ Subcommands
      >>> args.func(args)
      ((XYZYX))
 
-   This way, you can let :meth:`parse_args` do the job of calling the
+   This way, you can let :meth:`~ArgumentParser.parse_args` do the job of calling the
    appropriate function after argument parsing is complete.  Associating
    functions with actions like this is typically the easiest way to handle the
    different actions for each of your subparsers.  However, if it is necessary
    to check the name of the subparser that was invoked, the ``dest`` keyword
-   argument to the :meth:`add_subparsers` call will work::
+   argument to the :meth:`~ArgumentParser.add_subparsers` call will work::
 
      >>> parser = argparse.ArgumentParser()
      >>> subparsers = parser.add_subparsers(dest='subparser_name')
@@ -1922,6 +1896,49 @@ Subcommands
       the main parser.
 
 
+.. method:: _SubParsersAction.add_parser(name, *, help=None, aliases=None,
+                                           deprecated=False, **kwargs)
+
+   Creates and returns a new :class:`!ArgumentParser` object for the
+   subcommand *name*.
+
+   The *name* argument is the name of the sub-command.
+
+   The *help* argument provides a short description for this sub-command.
+   If provided, it will be listed next to the command in the main parser’s
+   help message (for example, ``PROG --help``).
+
+   The *aliases* argument allows providing alternative names for this
+   sub-command.
+
+   For example::
+
+      >>> parser = argparse.ArgumentParser()
+      >>> subparsers = parser.add_subparsers()
+      >>> checkout = subparsers.add_parser('checkout', aliases=['co'])
+      >>> checkout.add_argument('foo')
+      >>> parser.parse_args(['co', 'bar'])
+      Namespace(foo='bar')
+
+   The *deprecated* argument, if ``True``, marks the sub-command as
+   deprecated and will issue a warning when used.
+
+   For example::
+
+      >>> parser = argparse.ArgumentParser(prog='chicken.py')
+      >>> subparsers = parser.add_subparsers()
+      >>> fly = subparsers.add_parser('fly', deprecated=True)
+      >>> parser.parse_args(['fly'])  # doctest: +SKIP
+      chicken.py: warning: command 'fly' is deprecated
+      Namespace()
+
+   .. versionadded:: 3.13
+      Added the *deprecated* parameter.
+
+
+   All other keyword arguments are passed directly to the
+   :class:`!ArgumentParser` constructor.
+
 FileType objects
 ^^^^^^^^^^^^^^^^
 

Misc/NEWS.d/next/Documentation/2025-10-25-14-08-42.gh-issue-84116.lKcoHw.rst

@@ -0,0 +1,3 @@
+Document ``help`` and ``aliases`` parameters for
+``argparse._SubParsersAction.add_parser`` in the :mod:`argparse`
+documentation.