How to¶

Registered directives and roles¶

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

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",
]

Source on GitHub · PyPI