Extending results of argparse directivesΒΆ

You can add extra content or even replace some parts of the documentation generated by the argparse directive. For example, any content you put inside directives (you must follow ReStructuredText identation rules) will be inserted just before the argument and option list:

.. argparse::
    :module: my.module
    :func: my_func_that_return_parser
    :prog: fancytool

    My content here that will be inserted right before the argument list.

    Also any valid markup...
    *************************

    ... may `be` *applied* here

    including::

         any directives you usually use.

Also, there is an option to insert custom content into a specific argument/option/subcommand/argument-group description. Just create a name:definition pair, where the name is an argument/option/subcommand/argument-group name and the definition is any reStructured markup. Changes to options/arguments appearing in multiple action groups can either be targeted (i.e., only one instance of the argument is changed) or general (i.e., all instances are modified).:

.. argparse::
    :module: my.module
    :func: my_func_that_return_parser
    :prog: fancytool

    My content here that will be inserted right before the argument list.

    foo
         This text will go right after the "foo" positional argument help.

    install
         This text will go right after the "install" subcommand help and before its arguments.

         --upgrade -u
             This text will go after the upgrade option of the install subcommand. Nesting is unlimited.
             Note the space between --upgrade and -u, which differs from the comma that would normally
             be used.

     --output -o
         Content appended to the --output option, regardless of the argument group.

You can also add classifiers, which will change how these definitions are incorporated:

.. argparse::
    :module: my.module
    :func: my_func_that_return_parser
    :prog: fancytool

    My content that will be inserted right before the argument list.

    foo : @before
         This text will go before the "foo" positional argument help.

    install : @replace
         This text will replace the "install" subcommand help/description.

         --upgrade : @after
             The after directive is the default, so you needn't specify it.
@before
Insert content before the parsed help/description message of the argument/option/subcommand/argument-group.
@after
Insert content after the parsed help/description message of argument/option/subcommand/argument-group. This is the default.
@replace
Replace content of help/description message of argument/option/subcommand/argument-group.