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