Basic usage¶
Extension adds “argparse” directive:
.. argparse::
:module: my.module
:func: my_func_that_returns_a_parser
:prog: fancytool
module, func and prog options are required.
func is function that returns an instance of the argparse.ArgumentParser class.
Alternative syntax is to use :ref: like this:
.. argparse::
:ref: my.module.my_func_that_returns_a_parser
:prog: fancytool
in this case :ref: also may point directly to argument parser instance.
For this directive to work, you should point it to the function, that will return pre-filled ArgumentParser. Something like:
def my_func_that_return_parser():
parser = argparse.ArgumentParser()
parser.add_argument('foo', default=False, help='foo help')
parser.add_argument('bar', default=False)
subparsers = parser.add_subparsers()
subparser = subparsers.add_parser('install', help='install help')
subparser.add_argument('ref', type=str, help='foo1 help')
subparser.add_argument('--upgrade', action='store_true', default=False, help='foo2 help')
return parser
Note
We will use this example as a reference for every example in this doc.
- :module:
- Module name, where the function is located
- :func:
- Function name
- :prog:
- It’s just name of your tool (or how it’s should appear in your documentation). Ex. if you run your script as ./boo –some args then :prog: will be “boo”
That’s it. Directive will render positional arguments, options and sub-commands.
Sub-commands are limited to one level. But, you always can output help for subcommands separately:
.. argparse::
:module: my.module
:func: my_func_that_return_parser
:prog: fancytool
:path: install
This will render same doc for “install” subcommand.
Nesting level is not limited:
.. argparse::
:module: my.module
:func: my_func_that_return_parser
:prog: fancytool
:path: install subcomand1 subcommand2 subcommand3
Other useful directives¶
nodefault: | will hide all default values of options. |
---|