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>