Examples¶
Example documentation structure¶
Here is an example structure for the documentation of a complex command with many 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 utilities
**********************
.. toctree::
:maxdepth: 1
cmd_main
cmd_subcommand
File “cmd_main.rst”:
Fancytool command
***********************
.. argparse::
:module: my.module
:func: my_func_that_returns_a_parser
:prog: fancytool
subcommand
Here we add a 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()
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_command1.add_argument(
'default_string',
default='I am a default',
help='Ensure variables are filled in %(prog)s (default %(default)s)',
)
my_command2 = subparsers.add_parser('game', help='Decision games')
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'
)
optional = my_command2.add_argument_group('Group 1')
optional.add_argument(
'--addition',
choices=['Spock', 'lizard'],
help='Extra choices for additional group.',
)
optional.add_argument(
'--lorem_ipsum',
help='Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod '
'tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, '
'quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo '
'consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse '
'cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat '
'non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.',
)
Generated sample 1 - command with subcommands¶
Directive¶
Source:
.. argparse::
:filename: ../test/sample.py
:func: parser
:prog: sample
Output¶
usage: sample [-h] {apply,game} ...
Sub-commands¶
apply¶
Execute provision script, collect all resources and apply them.
sample apply [-h] [-r] [--tree] [--dry] [--force] path default_string
Positional Arguments¶
- path
Specify path to provision script. provision.py in current directory by default. Also may include url.
Default:
'provision.py'
- default_string
Ensure variables are filled in (default ‘I am a default’)
Default:
'I am a default'
Named Arguments¶
- -r, --rollback
If specified will rollback all resources applied.
Default:
False
- --tree
Print resource tree
Default:
False
- --dry
Just print changes list
Default:
False
- --force
Apply without confirmation
Default:
False
game¶
Decision games
sample game [-h] [--opt {rock,paper,scissors}] [--addition {Spock,lizard}]
[--lorem_ipsum LOREM_IPSUM]
{rock,paper,scissors}
Positional Arguments¶
- move
Possible choices: rock, paper, scissors
Choices for argument example
Named Arguments¶
- --opt
Possible choices: rock, paper, scissors
Choices for option example
Group 1¶
- --addition
Possible choices: Spock, lizard
Extra choices for additional group.
- --lorem_ipsum
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Generated sample 2 - subcommand¶
Directive¶
Source:
.. argparse::
:filename: ../test/sample.py
:func: parser
:prog: sample
:path: game
Output¶
usage: sample game [-h] [--opt {rock,paper,scissors}]
[--addition {Spock,lizard}] [--lorem_ipsum LOREM_IPSUM]
{rock,paper,scissors}
Positional Arguments¶
- move
Possible choices: rock, paper, scissors
Choices for argument example
Named Arguments¶
- --opt
Possible choices: rock, paper, scissors
Choices for option example
Group 1¶
- --addition
Possible choices: Spock, lizard
Extra choices for additional group.
- --lorem_ipsum
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.