API Reference¶

Cross-reference roles¶

Every argparse directive 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:

Directive and role reference¶

Base `argparse` directive¶

.. argparse:: ¶ directive directive .. argparse:: ¶

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 option :func: ¶: Validator: unchanged_required.

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

:module: ¶ option option :module: ¶: Validator: unchanged_required.

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

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

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

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

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

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

:nodefault: ¶ option option :nodefault: ¶: Validator: flag.

:nodescription: ¶ option option :nodescription: ¶: Validator: flag.

:noepilog: ¶ option option :noepilog: ¶: Validator: flag.

:nosubcommands: ¶ option option :nosubcommands: ¶: Validator: flag.

:path: ¶ option option :path: ¶: Validator: unchanged.

:prog: ¶ option option :prog: ¶: Validator: unchanged.

Exemplar override¶

.. cleanargparse:: ¶ directive directive .. cleanargparse:: ¶

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 option :func: ¶: Validator: unchanged_required.

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

:module: ¶ option option :module: ¶: Validator: unchanged_required.

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

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

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

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

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

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

:nodefault: ¶ option option :nodefault: ¶: Validator: flag.

:nodescription: ¶ option option :nodescription: ¶: Validator: flag.

:noepilog: ¶ option option :noepilog: ¶: Validator: flag.

:nosubcommands: ¶ option option :nosubcommands: ¶: Validator: flag.

:path: ¶ option option :path: ¶: Validator: unchanged.

:prog: ¶ option option :prog: ¶: Validator: unchanged.

CLI role callables¶

:cli-choice: ¶ role role :cli-choice: ¶

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 :cli-command: ¶

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 :cli-default: ¶

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 :cli-metavar: ¶

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 :cli-option: ¶

Role for CLI options like –foo or -h.

Python path:: sphinx_autodoc_argparse.roles.cli_option_role

class:: class_option

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¶

argparse_group_title_prefix ¶ config html config html argparse_group_title_prefix ¶

Prefix for argument group titles

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

argparse_show_defaults ¶ config html config html argparse_show_defaults ¶

Show default values in argument docs

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

argparse_show_choices ¶ config html config html argparse_show_choices ¶

Show choice constraints

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

argparse_show_types ¶ config html config html argparse_show_types ¶

Show type information

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

Exemplar layer¶

argparse_examples_term_suffix ¶ config html config html argparse_examples_term_suffix ¶

Term suffix for detecting example definition lists

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

argparse_examples_base_term ¶ config html config html argparse_examples_base_term ¶

Base term for matching example sections

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

argparse_examples_section_title ¶ config html config html argparse_examples_section_title ¶

Section title for extracted examples

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

argparse_usage_pattern ¶ config html config html argparse_usage_pattern ¶

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 config html argparse_examples_command_prefix ¶

Prefix for example commands in code blocks

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

argparse_examples_code_language ¶ config html config html argparse_examples_code_language ¶

Language for example code blocks

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

argparse_examples_code_classes ¶ config html config html argparse_examples_code_classes ¶

CSS classes for example code blocks

Type:

list

Default:

['highlight-console']

Registered by:

sphinx_autodoc_argparse.exemplar.setup()

argparse_usage_code_language ¶ config html config html argparse_usage_code_language ¶

Language for usage code blocks

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

argparse_reorder_usage_before_examples ¶ config html config html argparse_reorder_usage_before_examples ¶

Move usage sections before examples sections

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

Extension entry point¶

sphinx_autodoc_argparse.setup(app) ¶ function[source] function[source] sphinx_autodoc_argparse.setup(app) ¶

Parameters:: app (Sphinx) – The Sphinx application object.
Returns:: Extension metadata.
Return type:: SetupDict