# Documenting command collections

Consider the following sample application, using `CommandCollection`:

    # file: cli.py
    import click

    main = click.Group(
        name='Principal Commands',
        help=(
            "Principal commands that are used in ``cli``.\n\n"
            "The section name and description are obtained using the name and "
            "description of the group passed as sources for |CommandCollection|_."
        ),
    )

    @main.command(help='CMD 1')
    def cmd1() -> None:
        print('call cmd 1')

    helpers = click.Group(
        name='Helper Commands',
        help="Helper commands for ``cli``.",
    )

    @helpers.command()
    def cmd2() -> None:
        "Helper command that has no option."
        pass

    @helpers.command()
    @click.option('--user', type=str)
    def cmd3(user: str) -> None:
        "Helper command with an option."
        pass

    cli = click.CommandCollection(
        name='cli',
        sources=[main, helpers],
        help='Some general info on ``cli``.',
    )

This can be documented using sphinx-click like so:

    .. click:: commandcollections.cli:cli
      :prog: cli
      :nested: full

The rendered example is shown below.

## cli

Some general info on `cli`.

    cli [OPTIONS] COMMAND [ARGS]...

### Principal Commands

Principal commands that are used in `cli`.

The section name and description are obtained using the name and description of the group passed as sources for `CommandCollection`.

#### cmd1

CMD 1

    cli cmd1 [OPTIONS]

### Helper Commands

Helper commands for `cli`.

#### cmd2

Helper command that has no option.

    cli cmd2 [OPTIONS]

#### cmd3

Helper command with an option.

    cli cmd3 [OPTIONS]

Options

--user <user>