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

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.

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

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

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}

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

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

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:

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:

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.

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.

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.

• tox
• pypa-build
• mdpo