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():
print('call cmd 1')
helpers = click.Group(name='Helper Commands', help="Helper commands for ``cli``.")
@helpers.command()
def cmd2():
"Helper command that has no option."
pass
@helpers.command()
@click.option('--user', type=str)
def cmd3(user):
"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>¶