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 automatically.

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 entirely:

.. 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.

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.

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

Configuration values (conf.py)

Live examples

• tox
• pypa-build
• mdpo