Skip to content
Back to top
View this page

# 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.