Documenting command collections¶
Consider the following sample application, using
# 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.
Some general info on
cli [OPTIONS] COMMAND [ARGS]...
Principal commands that are used in
The section name and description are obtained using the name and description of the group passed as sources for
cli cmd1 [OPTIONS]
Helper commands for
Helper command that has no option.
cli cmd2 [OPTIONS]
Helper command with an option.
cli cmd3 [OPTIONS]
- --user <user>¶