Interpretation guidelines for docstrings¶
Prerequisits for the docstrings¶
As mentioned earlier, this package uses the docrep package to extract the relevant informations from the docstring. Therefore your docstrings must obey the following rules:
They have to follow the numpy conventions (i.e. it should follow the conventions from the sphinx napoleon extension).
Your docstrings must either be
dedented
or start with a blank line.So this works:
>>> def my_func(a=1): ... """ ... Some description ... ... Parameters ... ---------- ... a: int ... The documentation of a""" ... pass
This doesn’t:
>>> def my_func(a=1): ... """Some description ... ... Parameters ... ---------- ... a: int ... The documentation of a""" ... pass
Default interpretations¶
To make common arguments more accessible, the setup_args()
method already has some preconfigured settings:
non-optional (e.g.
name
indef my_func(name, a=1): ...
automatically get the'positional'
flag. You can remove that via:>>> parser.pop_key('<argname>', 'positional')
if the default argument in the function is a boolean and the specified type is
'bool'
(e.g.:>>> def my_func(switch=False): ... """ ... Some function ... ... Parameters ... ---------- ... switch: bool ... This will be inserted as a switch ... """ The default settings for the `switch` parameter are ``action='store_true'`` (or ``action='store_false'`` if the default value would be ``True``)
If the type specification in the docstring corresponds to a builtin type (e.g.
'float'
,'int'
,'str'
), this type will be used to interprete the commandline arguments. For example:>>> def my_func(num=0): ... """ ... Some function ... ... Parameters ... ---------- ... num: float ... A floating point number ... """
will for the
'num'
parameter lead to the settingstype=float
If the type description starts with
'list of'
, it will allow multiple arguments and interpretes everything after it as the type of it. For example:>>> def my_func(num=[1, 2, 3]): ... """ ... Some function ... ... Parameters ... ---------- ... num: list of floats ... Floating point numbers ... """
will lead to
type=float
nargs='+'
You can always disable the points 2-4 by setting interprete=False
in the
setup_args()
and setup_subparser()
call or you change the arguments by yourself by modifying the
unfinished_arguments
attribute, etc.
Epilog and descriptions¶
When calling the FuncArgParser.setup_args()
method or the
FuncArgParser.setup_subparser()
method, we interprete the Notes and
References methods as part of the epilog. And we interprete the description
of the function (i.e. the summary and the extended summary) as the description
of the parser. This is illustrated by this small example:
In [1]: from funcargparse import FuncArgParser
In [2]: def do_something(a=1):
...: """This is the summary and will go to the description
...:
...: This is the extended summary and will go to the description
...:
...: Parameters
...: ----------
...: a: int
...: This is a parameter that will be accessible as `-a` option
...:
...: Notes
...: -----
...: This section will appear in the epilog"""
...:
In [3]: parser = FuncArgParser(prog='do-something')
In [4]: parser.setup_args(do_something)
...: parser.create_arguments()
...:
Out[4]: [_StoreAction(option_strings=['-a'], dest='a', nargs=None, const=None, default=1, type=<class 'int'>, choices=None, help='This is a parameter that will be accessible as `-a` option', metavar='int')]
In [5]: parser.print_help()