sphinx-argparse-cli

PyPI PyPI - Implementation PyPI - Python Version Downloads PyPI - License check

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.

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

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

Project links

Data verified by PyPI on Aug 11, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

Owner

PyPI data
Data sourced directly from PyPI's database.

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for jugmac00 from gravatar.com jugmac00

Credits

Maintainer: Bernat Gabor

GitHub Statistics

Data verified by PyPI on Aug 11, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.11

Tags

argparse sphinx

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinx_argparse_cli-1.22.1.tar.gz (14.4 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

sphinx_argparse_cli-1.22.1-py3-none-any.whl (10.9 kB view details)

Uploaded Python 3

File details

Details for the file sphinx_argparse_cli-1.22.1.tar.gz.

File metadata

  • Download URL: sphinx_argparse_cli-1.22.1.tar.gz
  • Upload date:
  • Size: 14.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for sphinx_argparse_cli-1.22.1.tar.gz
Algorithm Hash digest
SHA256 d9279b28cd08891e148ef8422124525e797e7520d4ff18574aca52a33297713c
MD5 7c7d02e7aa0a94dd439ff4248a3d229a
BLAKE2b-256 8da56d1a540f987b2d531a2c80895d3580e77debca8af23b9c7d0342e95cad2b

See more details on using hashes here.

Provenance

The following attestation bundles were made for sphinx_argparse_cli-1.22.1.tar.gz:

Publisher: release.yaml on tox-dev/sphinx-argparse-cli

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sphinx_argparse_cli-1.22.1-py3-none-any.whl.

File metadata

File hashes

Hashes for sphinx_argparse_cli-1.22.1-py3-none-any.whl
Algorithm Hash digest
SHA256 a68d50a8b7ef7653facc30814c5396d81fc0037432498b14581eb0a78cd0dea0
MD5 6cde4d83f3b92d0a3ada1945271a3ba3
BLAKE2b-256 517032a41b652321a3956b2f635a03668a606c60e016b9decb51f15da3ea3150

See more details on using hashes here.

Provenance

The following attestation bundles were made for sphinx_argparse_cli-1.22.1-py3-none-any.whl:

Publisher: release.yaml on tox-dev/sphinx-argparse-cli

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.22.1 This release

2 files

1.22.0

2 files

1.21.4

2 files

1.21.3

2 files

1.21.2

2 files

1.21.1

2 files

1.21.0

2 files

1.20.1

2 files

1.20.0

2 files

1.19.0

2 files

1.18.2

2 files

1.18.1

2 files

1.18.0

2 files

1.17.0

2 files

1.16.0

2 files

1.15.0

2 files

1.14.0

2 files

1.13.1

2 files

1.13.0

2 files

1.12.0

2 files

1.11.1

2 files

1.11.0

2 files

1.10.0

2 files

1.9.0

2 files

1.8.3

2 files

1.8.2

2 files

1.8.1

2 files

1.8.0

2 files

1.7.0

2 files

1.6.0

2 files

1.5.2

2 files

1.5.1

2 files

1.5.0

2 files

1.4.0

2 files

1.3.0

2 files

1.2.0

2 files

1.1.0

2 files

1.0.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page