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 .. program:: and .. option:: directives.

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

extensions = ['sphinxcontrib.autoprogram']

See also

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

.. autoprogram:: directive

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

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

import argparse

parser = argparse.ArgumentParser(description='Process some integers.')
parser.add_argument('integers', metavar='N', type=int, nargs='+',
                    help='An integer for the accumulator.')
parser.add_argument('-i', '--identity', type=int, default=0,
                    help='the default result for no arguments '
                         '(default: 0)')
parser.add_argument('--sum', dest='accumulate', action='store_const',
                    const=sum, default=max,
                    help='Sum the integers (default: find the max).')

if __name__ == '__main__':
    args = parser.parse_args()
    print(args.accumulate(args.integers))

In order to document the above program:

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

That’s it. It will be rendered as:

cli.py

Process some integers.

usage: cli.py [-h] [-i IDENTITY] [–sum] N [N ...]

n

An integer for the accumulator.

-h, --help

show this help message and exit

-i <identity>, --identity <identity>

the default result for no arguments (default: 0)

--sum

Sum the integers (default: find the max).

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

import argparse

parser = argparse.ArgumentParser(description='Process some integers.')
subparsers = parser.add_subparsers()

max_parser = subparsers.add_parser('max', description='Find the max.')
max_parser.set_defaults(accumulate=max)
max_parser.add_argument('integers', metavar='N', type=int, nargs='+',
                        help='An integer for the accumulator.')

sum_parser = subparsers.add_parser('sum', description='Sum the integers.')
sum_parser.set_defaults(accumulate=sum)
sum_parser.add_argument('integers', metavar='N', type=int, nargs='+',
                        help='An integer for the accumulator.')

if __name__ == '__main__':
    args = parser.parse_args()
    print(args.accumulate(args.integers))
.. autoprogram:: subcmds:parser
   :prog: subcmds.py

The above reStructuredText will render:

subcmds.py

Process some integers.

usage: subcmds.py [-h] {max,sum} ...

-h, --help

show this help message and exit

subcmds.py max

Find the max.

usage: subcmds.py [-h] {max,sum} ...

n

An integer for the accumulator.

-h, --help

show this help message and exit

subcmds.py sum

Sum the integers.

usage: subcmds.py [-h] {max,sum} ...

n

An integer for the accumulator.

-h, --help

show this help message and exit

.. autoprogram:: module:parser

It takes an import name of the parser object. For example, if xyz variable in abcd.efgh module refers an argparse.ArgumentParser object:

.. autoprogram:: abcd.efgh:xyz

The import name also can evaluate other any Python expressions. For example, if get_parser() function in abcd.efgh module creates an argparse.ArgumentParser and returns it:

.. autoprogram:: abcd.efgh:get_parser()

It also optionally takes an option named prog. If it’s not present prog option uses ArgumentParser object’s prog value.

Author and license

The sphinxcontrib.autoprogram, a part of sphinxcontrib, is written by Hong Minhee and distributed under BSD license.

The source code is mantained under the common repository of contributed extensions for Sphinx (find the autoprogram directory inside the repository).

$ hg clone https://bitbucket.org/birkenfeld/sphinx-contrib
$ cd sphinx-contrib/autoprogram/

Changelog

Version 0.1.2

Released on August 18, 2015.

  • Fixed crash with empty fields. [issue #110]
  • Fixed ImportError with non-module Python scripts (i.e. files not ending with .py). [pull request #101 by Matteo Bachetti]

Version 0.1.1

Released on April 22, 2014.

  • Omit metavars of store_const/store_true/store_false options.
  • Sort subcommands in alphabetical order if Python 2.6 which doesn’t have collections.OrderedDict.

Version 0.1.0

Released on March 2, 2014. The first release.