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¶

Directive¶

Source:

.. argparse::
   :ref: test.sample.parser
   :prog: sample

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

Generated sample 2 - subcommand¶

Directive¶

Source:

.. argparse::
   :module: test.sample
   :func: parser
   :prog: sample
   :path: game

Output¶

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