Basic usage¶

This extension adds the “argparse” directive:

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

The module, func and prog options are required.

func is a function that returns an instance of the argparse.ArgumentParser class.

Alternatively, one can use :ref: like this:

.. argparse::
   :ref: my.module.my_func_that_returns_a_parser
   :prog: fancytool

In this case :ref: points directly to argument parser instance.

For this directive to work, you should point it to the function that will return a pre-filled ArgumentParser. Something like:

def my_func_that_return_parser():
    parser = argparse.ArgumentParser()
    parser.add_argument('foo', default=False, help='foo help')
    parser.add_argument('bar', default=False)

    subparsers = parser.add_subparsers()

    subparser = subparsers.add_parser('install', help='install help')
    subparser.add_argument('ref', type=str, help='foo1 help')
    subparser.add_argument('--upgrade', action='store_true', default=False, help='foo2 help')

    return parser

Note

We will use this example as a reference for every example in this document.

To document a file that is not part of a module, use :filename:

.. argparse::
   :filename: script.py
   :func: my_func_that_returns_a_parser
   :prog: script.py

The ‘filename’ option could be absolute path or a relative path under current working dir.

:module:: Module name, where the function is located
:func:: Function name
:ref:: A combination of :module: and :func:
:filename:: A file name, in cases where the file to be documented is not part of a module.
:prog:: The name of your tool (or how it should appear in the documentation). For example, if you run your script as ./boo –some args then :prog: will be “boo”

That’s it. Directives will render positional arguments, options and sub-commands.

About Sub-Commands¶

Sub-commands are limited to one level. But, you can always output help for subcommands separately:

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

This will render same doc for “install” subcommand.

Nesting level is unlimited:

.. argparse::
   :module: my.module
   :func: my_func_that_return_parser
   :prog: fancytool
   :path: install subcomand1 subcommand2 subcommand3

Other useful directives¶

nodefault:: Do not show any default values.
nodefaultconst:: Like nodefault:, except it applies only to arguments of types store_const, store_true and store_false.
nosubcommands:: Do not show subcommands.
noepilog:: Do not parse the epilogue, which can be useful if it contains text that could be incorrectly parse as reStructuredText.
nodescription:: Do not parse the description, which can be useful if it contains text that could be incorrectly parse as reStructuredText.
passparser:: This can be used if you don’t have a function that returns an argument parser, but rather adds commands to it (:func: is then that function).
index-groups:: This option is related to grouping related commands in an index.

Printing Fully Qualified Sub-Command Headings¶

By default, when a command has sub-commands, such as fancytool install shown in the About Sub-Commands section, the heading for the sub-command does not include the command name. For instance, the the heading is install rather than fancytool install.

If you prefer to show the full command, fancytool install, then you can enable the option in the conf.py for your project:

sphinx_argparse_conf = {
  "full_subcommand_name": True,
}

Indices¶

The extension supports two types of optional indices. The first type of index is a simple index that provides a list of all the commands in the project by fully qualified name and a link to each command. The second type of index enables you to group related commands into groups and then provide a list of the commands and a link to each command. By default, no index is created.

Simple Command Index¶

To enable the simple command index, add the following to the project conf.py file:

sphinx_argparse_conf = {
  "build_commands_index": True,
  "commands_index_in_toctree": True,
}

The first option, build_commands_index, instructs the extension to create the index. For an HTML build, the index is created with the file name commands-index.html in the output directory. You can reference the index from other files with the :ref:`commands-index` markup.

The second option, commands_index_in_toctree, enables you to reference the the index in a toctree directive. By default, you cannot reference indices generated by extensions in a toctree. When you enable this option, the extension creates a temporary file that is named commands-index.rst in the source directory of your project. Sphinx locates the temporary file and that makes it possible to reference the file in the toctree. When the Sphinx build finishes, the extension removes the temporary file from the source directory.

Commands by Group Index¶

To enable the more complex index, add the following to the project conf.py file:

sphinx_argparse_conf = {
  "build_commands_by_group_index": True,
  "commands_by_group_index_in_toctree": True,
}

Add the :index-groups: option to the argparse directive in your documentation files. Specify one or more groups that the command belongs to (comma-separated).

.. argparse::
   :filename: ../test/sample.py
   :func: parser
   :prog: sample
   :index-groups: Basic Commands

For an HTML build, the index is created with the file name commands-by-group.html in the output directory. You can cross reference the index from other files with the :ref:`commands-by-group` role.

Like the simple index, the commands_by_group_index_in_toctree option enables you to reference the index in toctree directives.

This index has two more options.

sphinx_argparse_conf = {
  "commands_by_group_index_in_toctree": True,
  "commands_by_group_index_file_suffix": "by-service",
  "commands_by_group_index_title": "Commands by Service",
}

The commands_by_group_index_file_suffix option overrides the default index name of commands-by-group.html. The value commands- is concatenated with the value you specify. In the preceding sample, the index file name is created as commands-by-service.html. If you specify this option, the default reference of :ref:`commands-by-group` is overridden with the value that you create.

The commands_by_group_index_title option overides the default first-level heading for the file. The default heading is “Commands by Group”. The value you specify replaces the default value.

Customizing the Indices¶

By default, indices are created with the domainindex.html template. If you want to customize the appearance of an index, copy the default domainindex.html file for your theme to the _templates directory in your project and modify it.

If you want to customize both indices, but one template cannot accommodate both of them, you can create an additional index template, such as customindex.html. You can configure Sphinx to use the additional template for an index by modifying the conf.py for the project like the following example.

def page_template(app: "Sphinx", pagename, templatename, context, doctree) -> str:
    if pagename == "commands-by-group":
        return "customindex.html"
    else:
        return templatename

def setup(app: "Sphinx"):
    app.connect('html-page-context', page_template)

For more information, refer to the Sphinx documentation for sphinx:templating and the sphinx:extdev/appapi.