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