sphinx-argparse-cli

Render CLI arguments (sub-commands friendly) defined by the argparse module.

Getting started

Install the package:

python -m pip install sphinx-argparse-cli

Add the extension to your conf.py:

extensions = ["sphinx_argparse_cli"]

Use the directive in any reStructuredText file:

.. sphinx_argparse_cli::
  :module: my_project.cli
  :func: build_parser

:module: points to the Python module containing the parser, and :func: names a zero-argument function that returns an ArgumentParser. Build your docs and the full CLI reference appears.

How-to guides

Override the program name

By default the program name comes from the parser. Use :prog: to replace it:

.. sphinx_argparse_cli::
  :module: my_project.cli
  :func: build_parser
  :prog: my-cli

Hook into a parser that is not returned

When a function creates and uses a parser internally without returning it, set the :hook: flag to intercept argparse.ArgumentParser:

.. sphinx_argparse_cli::
  :module: my_project.cli
  :func: main
  :hook:
  :prog: my-cli

Customize section titles

Control how group and subcommand headings are rendered with :group_title_prefix: and :group_sub_title_prefix:. Both accept {prog} and the sub-title also accepts {subcommand}:

.. sphinx_argparse_cli::
  :module: my_project.cli
  :func: build_parser
  :group_title_prefix: {prog}
  :group_sub_title_prefix: {prog} {subcommand}

Suppress default values

Hide (default: ...) annotations from the output:

.. sphinx_argparse_cli::
  :module: my_project.cli
  :func: build_parser
  :no_default_values:

Control usage display

Set the character width for usage lines and optionally show usage before the description:

.. sphinx_argparse_cli::
  :module: my_project.cli
  :func: build_parser
  :usage_width: 80
  :usage_first:

Override title, description, or epilog

Replace auto-detected values, or pass an empty string to suppress them:

.. sphinx_argparse_cli::
  :module: my_project.cli
  :func: build_parser
  :title: Custom Title
  :description: Custom description text.
  :epilog:

Cross-reference generated anchors

The directive registers Sphinx reference labels for every command, group, and flag. Use the :ref: role to link to them.

With sphinx_argparse_cli_prefix_document = False (default):

:ref:`tox-optional-arguments`
:ref:`tox-run`
:ref:`tox-run---magic`

With sphinx_argparse_cli_prefix_document = True (anchors prefixed by document name, avoids clashes across documents):

:ref:`cli:tox-optional-arguments`
:ref:`cli:tox-run`
:ref:`cli:tox-run---magic`

The anchor text is visible after the # in the URL when you click a heading.

Flags and positional arguments are also registered as Sphinx program options, so the :option: role works with the program (and sub-command) name followed by the argument, or scoped through a .. program:: directive:

:option:`tox --magic`
:option:`tox run --magic`

.. program:: tox run

:option:`--magic`
:option:`--magic=value`

:option: targets keep their original case, so they do not need :force_refs_lower:. They ignore sphinx_argparse_cli_prefix_document; when two documents render the same program, the role links to the first one Sphinx reads.

Handle mixed-case references

Sphinx :ref: only supports lower-case targets. When your program name or flags contain capital letters, set :force_refs_lower: to convert them. Each upper-case letter becomes its lower-case form prefixed with _ (e.g. A becomes _a):

.. sphinx_argparse_cli::
  :module: my_project.cli
  :func: build_parser
  :force_refs_lower:

For a program named SampleProgram:

:ref:`_sample_program--a`   .. flag -a
:ref:`_sample_program--_a`  .. flag -A

If you do not need Sphinx :ref: cross-references you can leave this off to keep mixed-case anchors in the HTML output, but enabling it later will change existing anchor URLs.

Write help text as reStructuredText

The directive parses every argument's help string as reStructuredText, so inline markup such as a :ref: role or **bold** works. The same applies to characters that carry meaning in reStructuredText: a lone * (match *.py), a trailing _ (name_), backticks, or a trailing :: produce docutils warnings and fail a build run with -W. Escape them with a backslash (match \*.py) or wrap them in inline literals. Text between matching single quotes, double quotes, or braces becomes an inline literal for you, so pick 'fast' or "slow" shows 'fast' and "slow" as code.

Add extra content after generated docs

Any content nested inside the directive is appended after the generated CLI documentation:

.. sphinx_argparse_cli::
  :module: my_project.cli
  :func: build_parser

  Extra notes or examples rendered after the CLI reference.

Reference

Directive options

Option	Type	Default	Description
:module:	string	required	Python module path where the parser is defined
:func:	string	required	Zero-argument function that returns an ArgumentParser
:prog:	string	parser's prog	Override the displayed program name
:hook:	flag	off	Intercept ArgumentParser instead of expecting func to return it
:title:	string	<prog> - CLI interface	Custom title; empty string suppresses it
:description:	string	parser's description	Custom description; empty string suppresses it
:epilog:	string	parser's epilog	Custom epilog; empty string suppresses it
:usage_width:	int	100	Character width for usage lines
:usage_first:	flag	off	Show usage before the description
:group_title_prefix:	string	{prog}	Heading prefix for groups; {prog} is replaced with the program name
:group_sub_title_prefix:	string	{prog} {subcommand}	Heading prefix for subcommand groups; supports {prog} and {subcommand}
:no_default_values:	flag	off	Suppress (default: ...) annotations
:force_refs_lower:	flag	off	Lower-case reference anchors with _ prefix for capitals (for :ref: compat)

Configuration values (conf.py)

Name	Type	Default	Description
sphinx_argparse_cli_prefix_document	bool	False	Prefix reference anchors with the document name to avoid clashes

Live examples

• tox
• pypa-build
• mdpo