sphinx-autodoc-argparse¶

Alpha GitHub PyPI

Modern Sphinx extension for documenting argparse CLIs. The base package registers the argparse directive plus renderer config values; the sphinx_autodoc_argparse.exemplar layer adds example extraction, lexers, and CLI inline roles.

$ pip install sphinx-autodoc-argparse

Working usage examples¶

extensions = [
    "sphinx_autodoc_argparse",
    "sphinx_autodoc_argparse.exemplar",
]

argparse_examples_section_title = "Examples"
argparse_reorder_usage_before_examples = True

Live demos¶

Base parser rendering¶

Example CLI showing how sphinx-autodoc-argparse renders parsers.

Usage¶

usage: myapp [-h] [--verbose] [--config PATH]
             {mysubcommand,myothersubcommand} ...

Options¶

--verbose, -v¶

Enable verbose output.

Default: False

--config PATH¶

Path to configuration file.

Default: pyproject.toml

Sub-commands

mysubcommand

Run the primary task.

Execute the primary task with configurable output.

Usage¶

usage: myapp mysubcommand [-h] [--output DIR] [--format {text,json}] [--clean]

Options¶

--output, -o DIR¶

Output directory.

Default: build

--format¶

Output format.

Default: text
Choices: text, json

--clean¶

Remove previous output first.

Default: False

myothersubcommand

Run a secondary task.

Execute a secondary task with network options.

Usage¶

usage: myapp myothersubcommand [-h] [--port PORT] [--host HOST]

Options¶

--port¶

Port number.

Default: 8000
Type: int

--host¶

Host to bind to.

Default: localhost

Subcommand rendering¶

Drill into a single subcommand with :path::

Execute the primary task with configurable output.

Usage¶

usage: myapp mysubcommand [-h] [--output DIR] [--format {text,json}] [--clean]

Options¶

--output, -o DIR¶

Output directory.

Default: build

--format¶

Output format.

Default: text
Choices: text, json

--clean¶

Remove previous output first.

Default: False

Inline roles¶

The exemplar layer also registers live inline roles for CLI prose: myapp, --verbose, json, DIR, and text.

Cross-reference roles¶

Every .. argparse:: block populates a dedicated argparse domain alongside the existing std:cmdoption entries. Use these roles to link to programs, options, subcommands, and positional arguments declared anywhere in the project:

Role	Resolves to	Example
`:argparse:program:`	A top-level program	:argparse:program:`myapp`
`:argparse:option:`	An optional flag, scoped by program	:argparse:option:`myapp --verbose` or :argparse:option:`myapp sync --force`
`:argparse:subcommand:`	A subcommand under a parent program	:argparse:subcommand:`myapp sync`
`:argparse:positional:`	A positional argument, scoped by program	:argparse:positional:`myapp FILE`

Whitespace-joined targets (myapp sync --force) are split on the final space to match the stored (program, name) tuple. Bare forms (--verbose) also resolve when only one registration matches, though the fully-qualified form is preferred for multi-program sites.

Auto-generated indices¶

Two domain indices are built into every project that loads the extension:

argparse-programsindex — alphabetised list of every registered program; link via :ref:`argparse-programsindex`.
argparse-optionsindex — options grouped by program, alphabetised within each group; link via :ref:`argparse-optionsindex`.

Intersphinx compatibility¶

The classic :option: / std:cmdoption emission is preserved — both roles resolve and both appear in objects.inv. Downstream consumers linking via intersphinx continue to work; new authoring inside projects using this extension can prefer the :argparse:* namespace for program-scoped clarity.

Configuration values¶

Base extension¶

Config Value Index

Name	Type	Default	Rebuild
`argparse_group_title_prefix`	`str`	`''`	`html`
`argparse_show_defaults`	`bool`	`True`	`html`
`argparse_show_choices`	`bool`	`True`	`html`
`argparse_show_types`	`bool`	`True`	`html`

argparse_group_title_prefix ¶ config html

Prefix for argument group titles

Type:: str
Default:: ''
Registered by:: sphinx_autodoc_argparse.setup()

argparse_show_defaults ¶ config html

Show default values in argument docs

Type:: bool
Default:: True
Registered by:: sphinx_autodoc_argparse.setup()

argparse_show_choices ¶ config html

Show choice constraints

Type:: bool
Default:: True
Registered by:: sphinx_autodoc_argparse.setup()

argparse_show_types ¶ config html

Show type information

Type:: bool
Default:: True
Registered by:: sphinx_autodoc_argparse.setup()

Exemplar layer¶

Config Value Index

Name	Type	Default	Rebuild
`argparse_examples_term_suffix`	`str`	`'examples'`	`html`
`argparse_examples_base_term`	`str`	`'examples'`	`html`
`argparse_examples_section_title`	`str`	`'Examples'`	`html`
`argparse_usage_pattern`	`str`	`'usage:'`	`html`
`argparse_examples_command_prefix`	`str`	`'$ '`	`html`
`argparse_examples_code_language`	`str`	`'console'`	`html`
`argparse_examples_code_classes`	`list`	`['highlight-console']`	`html`
`argparse_usage_code_language`	`str`	`'cli-usage'`	`html`
`argparse_reorder_usage_before_examples`	`bool`	`True`	`html`

argparse_examples_term_suffix ¶ config html

Term suffix for detecting example definition lists

Type:: str
Default:: 'examples'
Registered by:: sphinx_autodoc_argparse.exemplar.setup()

argparse_examples_base_term ¶ config html

Base term for matching example sections

Type:: str
Default:: 'examples'
Registered by:: sphinx_autodoc_argparse.exemplar.setup()

argparse_examples_section_title ¶ config html

Section title for extracted examples

Type:: str
Default:: 'Examples'
Registered by:: sphinx_autodoc_argparse.exemplar.setup()

argparse_usage_pattern ¶ config html

Pattern to detect usage blocks in epilog text

Type:: str
Default:: 'usage:'
Registered by:: sphinx_autodoc_argparse.exemplar.setup()

argparse_examples_command_prefix ¶ config html

Prefix for example commands in code blocks

Type:: str
Default:: '$ '
Registered by:: sphinx_autodoc_argparse.exemplar.setup()

argparse_examples_code_language ¶ config html

Language for example code blocks

Type:: str
Default:: 'console'
Registered by:: sphinx_autodoc_argparse.exemplar.setup()

argparse_examples_code_classes ¶ config html

CSS classes for example code blocks

Type:: list
Default:: ['highlight-console']
Registered by:: sphinx_autodoc_argparse.exemplar.setup()

argparse_usage_code_language ¶ config html

Language for usage code blocks

Type:: str
Default:: 'cli-usage'
Registered by:: sphinx_autodoc_argparse.exemplar.setup()

argparse_reorder_usage_before_examples ¶ config html

Move usage sections before examples sections

Type:: bool
Default:: True
Registered by:: sphinx_autodoc_argparse.exemplar.setup()

Registered directives and roles¶

Base `argparse` directive¶

.. argparse:: directive

Sphinx directive for documenting argparse-based CLI tools.

Options:

Python path:: sphinx_autodoc_argparse.directive.ArgparseDirective
Required arguments:: 0
Optional arguments:: 0
Final argument whitespace:: False
Has content:: True

:func: option: Validator: unchanged_required.

:mock-modules: option: Validator: unchanged.

:module: option: Validator: unchanged_required.

:no-choices: option: Validator: flag.

:no-defaults: option: Validator: flag.

:no-description: option: Validator: flag.

:no-epilog: option: Validator: flag.

:no-types: option: Validator: flag.

:nodefault: option: Validator: flag.

:nodescription: option: Validator: flag.

:noepilog: option: Validator: flag.

:nosubcommands: option: Validator: flag.

:path: option: Validator: unchanged.

:prog: option: Validator: unchanged.

Exemplar override¶

.. cleanargparse:: ¶ directive

ArgParse directive that strips ANSI codes and formats examples.

Options:

Python path:: sphinx_autodoc_argparse.exemplar.CleanArgParseDirective
Required arguments:: 0
Optional arguments:: 0
Final argument whitespace:: False
Has content:: True

:func: ¶ option: Validator: unchanged_required.

:mock-modules: ¶ option: Validator: unchanged.

:module: ¶ option: Validator: unchanged_required.

:no-choices: ¶ option: Validator: flag.

:no-defaults: ¶ option: Validator: flag.

:no-description: ¶ option: Validator: flag.

:no-epilog: ¶ option: Validator: flag.

:no-types: ¶ option: Validator: flag.

:nodefault: ¶ option: Validator: flag.

:nodescription: ¶ option: Validator: flag.

:noepilog: ¶ option: Validator: flag.

:nosubcommands: ¶ option: Validator: flag.

:path: ¶ option: Validator: unchanged.

:prog: ¶ option: Validator: unchanged.

CLI role callables¶

Role Index

Name	Python path	Summary
`cli-choice`	`sphinx_autodoc_argparse.roles.cli_choice_role`	Role for CLI choice values like json or yaml.
`cli-command`	`sphinx_autodoc_argparse.roles.cli_command_role`	Role for CLI command names like sync or add.
`cli-default`	`sphinx_autodoc_argparse.roles.cli_default_role`	Role for CLI default values like None or “default”.
`cli-metavar`	`sphinx_autodoc_argparse.roles.cli_metavar_role`	Role for CLI metavar placeholders like FILE or PATH.
`cli-option`	`sphinx_autodoc_argparse.roles.cli_option_role`	Role for CLI options like –foo or -h.

:cli-choice: ¶ role

Role for CLI choice values like json or yaml.

Python path:: sphinx_autodoc_argparse.roles.cli_choice_role

class:: class_option

:cli-command: ¶ role

Role for CLI command names like sync or add.

Python path:: sphinx_autodoc_argparse.roles.cli_command_role

class:: class_option

:cli-default: ¶ role

Role for CLI default values like None or “default”.

Python path:: sphinx_autodoc_argparse.roles.cli_default_role

class:: class_option

:cli-metavar: ¶ role

Role for CLI metavar placeholders like FILE or PATH.

Python path:: sphinx_autodoc_argparse.roles.cli_metavar_role

class:: class_option

:cli-option: ¶ role

Role for CLI options like –foo or -h.

Python path:: sphinx_autodoc_argparse.roles.cli_option_role

class:: class_option

Downstream usage snippets¶

Use native MyST directives in Markdown:

```{argparse}
:module: myproject.cli
:func: create_parser
:prog: myproject
```

Or reStructuredText:

.. argparse::
   :module: myproject.cli
   :func: create_parser
   :prog: myproject

Copyable config snippet

extensions = [
    "sphinx_autodoc_argparse",
    "sphinx_autodoc_argparse.exemplar",
]

Package metadata

Source on GitHub: sphinx-autodoc-argparse
PyPI: sphinx-autodoc-argparse
Maturity: Alpha

Registered Surface

sphinx_autodoc_argparse

Config values

Name	Default	Rebuild	Types
`argparse_group_title_prefix`	`''`	`html`	`str`
`argparse_show_defaults`	`True`	`html`	`bool`
`argparse_show_choices`	`True`	`html`	`bool`
`argparse_show_types`	`True`	`html`	`bool`

Directives

Name	Kind	Callable	Summary
`argparse`	directive	`ArgparseDirective`	Sphinx directive for documenting argparse-based CLI tools.

argparse options

Option
`:func:`	Registered option
`:mock-modules:`	Registered option
`:module:`	Registered option
`:no-choices:`	Registered option
`:no-defaults:`	Registered option
`:no-description:`	Registered option
`:no-epilog:`	Registered option
`:no-types:`	Registered option
`:nodefault:`	Registered option
`:nodescription:`	Registered option
`:noepilog:`	Registered option
`:nosubcommands:`	Registered option
`:path:`	Registered option
`:prog:`	Registered option

sphinx_autodoc_argparse.exemplar

Config values

Name	Default	Rebuild	Types
`argparse_examples_term_suffix`	`'examples'`	`html`	`str`
`argparse_examples_base_term`	`'examples'`	`html`	`str`
`argparse_examples_section_title`	`'Examples'`	`html`	`str`
`argparse_usage_pattern`	`'usage:'`	`html`	`str`
`argparse_examples_command_prefix`	`'$ '`	`html`	`str`
`argparse_examples_code_language`	`'console'`	`html`	`str`
`argparse_examples_code_classes`	`['highlight-console']`	`html`	`list`
`argparse_usage_code_language`	`'cli-usage'`	`html`	`str`
`argparse_reorder_usage_before_examples`	`True`	`html`	`bool`

Directives

Name	Kind	Callable	Summary
`argparse`	directive	`CleanArgParseDirective`	ArgParse directive that strips ANSI codes and formats examples.

argparse options

Option
`:func:`	Registered option
`:mock-modules:`	Registered option
`:module:`	Registered option
`:no-choices:`	Registered option
`:no-defaults:`	Registered option
`:no-description:`	Registered option
`:no-epilog:`	Registered option
`:no-types:`	Registered option
`:nodefault:`	Registered option
`:nodescription:`	Registered option
`:noepilog:`	Registered option
`:nosubcommands:`	Registered option
`:path:`	Registered option
`:prog:`	Registered option

Roles

Name	Kind	Callable	Summary
`cli-option`	role	`cli_option_role`	Role for CLI options like –foo or -h.
`cli-metavar`	role	`cli_metavar_role`	Role for CLI metavar placeholders like FILE or PATH.
`cli-command`	role	`cli_command_role`	Role for CLI command names like sync or add.
`cli-default`	role	`cli_default_role`	Role for CLI default values like None or “default”.
`cli-choice`	role	`cli_choice_role`	Role for CLI choice values like json or yaml.

Lexers

Name	Callable
`cli-usage`	`CLIUsageLexer`
`argparse`	`ArgparseLexer`
`argparse-usage`	`ArgparseUsageLexer`
`argparse-help`	`ArgparseHelpLexer`

Source on GitHub · PyPI

sphinx-autodoc-argparse¶

Working usage examples¶

Live demos¶

Base parser rendering¶

Usage¶

Options¶

mysubcommand

Usage¶

Options¶

myothersubcommand

Usage¶

Options¶

Subcommand rendering¶

Usage¶

Options¶

Inline roles¶

Cross-reference roles¶

Auto-generated indices¶

Intersphinx compatibility¶

Configuration values¶

Base extension¶

Exemplar layer¶

Registered directives and roles¶

Base argparse directive¶

Exemplar override¶

CLI role callables¶

Downstream usage snippets¶

Base `argparse` directive¶