sphinxcontrib.autoprogram
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.
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
: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
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