index.rst

sphinxcontrib.autoprogram

sphinxcontrib.autoprogram --- Documenting CLI programs

This contrib extension, sphinxcontrib.autoprogram, provides an automated way to document CLI programs. It scans argparse.ArgumentParser object, and then expands it into a set of :rst.. program:: and :rst.. option:: directives.

In order to use it, add sphinxcontrib.autoprogram into extensions list of your Sphinx configuration file (conf.py):

extensions = ['sphinxcontrib.autoprogram']

Module argparse

This extension assumes a program to document is made using argparse module which is a part of the Python standard library.

:rst.. autoprogram:: directive

Its only and simple way to use is :rst.. autoprogram:: directive. It's similar to sphinx.ext.autodoc extension's :rst.. automodule:: and other directives.

For example, given the following Python CLI program (say it's cli.py):

In order to document the above program:

.. autoprogram:: cli:parser
   :prog: cli.py

That's it. It will be rendered as:

cli:parser

If there are subcommands (subparsers), they are rendered to subsections. For example, given the following Python CLI program (say it's subcmds.py):

.. autoprogram:: subcmds:parser
   :prog: subcmds.py

The above reStructuredText will render:

subcmds:parser

If there are argument groups, they can optionally be rendered as subsections, just like subcommands. For example:

.. autoprogram:: cli_with_groups:parser
    :prog: cli_with_groups.py
    :groups:

The above reStructuredText Text will render:

cli_with_groups:parser

Additional Options for :rst.. autoprogram::

:groups:

Render argument groups as subsections.

0.1.5

:maxdepth: ##

Only show subcommands to a depth of ##.

0.1.3

:no_usage_codeblock:

Don't put the usage text in a :rst.. codeblock:: console directive.

0.1.3

:start_command: subcommand

Render document for the given subcommand. subcommand can be a space separated list to render a sub-sub-...-command.

0.1.3

:strip_usage:

Removes all but the last word in the usage string before the first option, replaces it with '...', and removes an amount of whitespace to realign subsequent lines.

0.1.3

Author and license

The sphinxcontrib.autoprogram is written by Hong Minhee and distributed under BSD license.

The source code is maintained under the GitHub repository:

console

$ git clone git://github.com/sphinx-contrib/autoprogram.git