Examples¶
Example structure of pages¶
Here is example structure of documentation for complex commands with lots of subcommands. You are free to use any structure, but this may be a good starting point.
File “index.rst”:
.. toctree::
:maxdepth: 2
cmd
File “cmd.rst”:
Command line utitlites
***********************
.. toctree::
:maxdepth: 1
cmd_main
cmd_subcommand
File “cmd_main.rst”:
Fancytool command
***********************
.. argparse::
:module: my.module
:func: my_func_that_return_parser
:prog: fancytool
subcommand
Here we add reference to subcommand, to simplify navigation.
See :doc:`cmd_subcommand`
File “cmd_subcommand.rst”:
Subcommand command
***********************
.. argparse::
:module: my.module
:func: my_func_that_return_parser
:prog: fancytool
:path: subcommand
Source of example file¶
This file will be used in all generated examples.
import argparse
parser = argparse.ArgumentParser()
parser.add_subparsers()
parser = argparse.ArgumentParser()
subparsers = parser.add_subparsers()
my_command1 = subparsers.add_parser('apply', help='Execute provision script, collect all resources and apply them.')
my_command1.add_argument('path', help='Specify path to provision script. provision.py in current'
'directory by default. Also may include url.', default='provision.py')
my_command1.add_argument('-r', '--rollback', action='store_true', default=False, help='If specified will rollback all'
'resources applied.')
my_command1.add_argument('--tree', action='store_true', default=False, help='Print resource tree')
my_command1.add_argument('--dry', action='store_true', default=False, help='Just print changes list')
my_command1.add_argument('--force', action='store_true', default=False, help='Apply without confirmation')
my_command2 = subparsers.add_parser('game')
my_command2.add_argument('move', choices=['rock', 'paper', 'scissors'], help='Choices for argument example')
my_command2.add_argument('--opt', choices=['rock', 'paper', 'scissors'], help='Choices for option example')
Generated sample 1 - command with subcommands¶
Output¶
usage: sample [-h] {apply,game} ...
- Sub-commands:
- apply
Execute provision script, collect all resources and apply them.
usage: sample apply [-h] [-r] [--tree] [--dry] [--force] path
- Positional arguments:
path Specify path to provision script. provision.py in currentdirectory by default. Also may include url. - Options:
-r=False, --rollback=False If specified will rollback allresources applied. --tree=False Print resource tree --dry=False Just print changes list --force=False Apply without confirmation
- game
Undocumented
usage: sample game [-h] [--opt {rock,paper,scissors}] {rock,paper,scissors}
- Positional arguments:
move Choices for argument example
Possible choices: rock, paper, scissors
- Options:
--opt Choices for option example
Possible choices: rock, paper, scissors