Documenting commands

Consider the following sample application, using Command:

# file: cli.py
import click


@click.command()
@click.option('--param', envvar='PARAM', help='A sample option')
@click.option('--another', metavar='[FOO]', help='Another option')
@click.option(
    '--choice',
    help='A sample option with choices',
    type=click.Choice(['Option1', 'Option2']),
)
@click.option(
    '--numeric-choice',
    metavar='<choice>',
    help='A sample option with numeric choices',
    type=click.Choice([1, 2, 3]),
)
@click.option(
    '--flag',
    is_flag=True,
    help='A boolean flag',
)
@click.argument('ARG', envvar='ARG')
def cli(
    param: str,
    another: str,
    choice: str,
    numeric_choice: int,
    flag: bool,
) -> None:
    """A sample command."""
    pass

This can be documented using sphinx-click like so:

.. click:: commands.cli:cli
  :prog: cli
  :nested: full

The rendered example is shown below.

---

cli

A sample command.

cli [OPTIONS] ARG

Options

--param <param>

A sample option

--another <FOO>

Another option

--choice <choice>

A sample option with choices

Options

Option1 | Option2

--numeric-choice <choice>

A sample option with numeric choices

Options

1 | 2 | 3

--flag

A boolean flag

Arguments

ARG

Required argument

Environment variables

PARAM

Provide a default for --param

ARG

Provide a default for ARG