Extending result of argparse directiveΒΆ

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

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

    My content here that will be inserted as extra, right before argument list.

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

    ... may `be` *applied* here

    including::

         any directives you usually use.

Also, there is an option to insert own content into argument/option/subcommand description. Just create definition-list, where name is argument/option/subcommand name and definition-body is any reStructured markup:

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

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

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

    install
         This text will go right after "install" subcommand help and before it's arguments.

         --upgrade
             This text will go to upgrade option of install subcommand, nesting is not limited

You can also add classifiers to definition-list that will change behavior of content merge algorythm:

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

    My content that will be inserted as extra, right before argument list.

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

    install : @replace
         This text will go right after "install" subcommand help and befor it's arguments.

         --upgrade : @after
             This text will go to upgrade option of install subcommand, nesting is not limited
@before
Insert content before parsed help message of argument/option/subcommand.
@after

Insert content after parsed help message of argument/option/subcommand.

This is default, if you do not specify classifier explicitly.

@replace
Replace content of help message of argument/option/subcommand.