def expected_func_choices(expected_func_defaults):
expected_func_defaults = copy.deepcopy(expected_func_defaults)
expected_func_defaults.type = examples.func_choices
choices = docstring.MultiType({'foo', 'bar'})
expected_func_defaults.args['foo'].type = choices
expected_func_defaults.args['bar'].type = choices
return expected_func_defaults
def expected_func_linking_args(expected_func_defaults):
expected_func_defaults.type = examples.func_linking_args
expected_func_defaults.args['boo'] = expected_func_defaults.args['foo']
expected_func_defaults.args['boo'].name = 'boo'
expected_func_defaults.args['far'] = expected_func_defaults.args['bar']
expected_func_defaults.args['far'].type = docstring.MultiType(
{'foo', 'bar'}, )
del expected_func_defaults.args['foo'], expected_func_defaults.args['bar']
return expected_func_defaults
def expected_func_linking_see_start(expected_func_defaults):
expected_func_defaults.type = examples.func_linking_see_start
expected_func_defaults.returns.description = \
'An incredible ordered concatenation of the ordered string inputs.'
desc = 'An excellently documented string argument.'
new_args = OrderedDict(
fizz=docstring.ArgDoc('fizz', str, desc, 'fizz'),
buzz=docstring.ArgDoc(
'buzz',
docstring.MultiType({'fizz', 'buzz'}),
desc,
'buzz',
),
)
expected_func_defaults.args.update(new_args)
return expected_func_defaults
def expected_func_linking_arg_pass_thru(expected_func_defaults):
expected_func_defaults.type = examples.func_linking_arg_pass_thru
expected_func_defaults.args['bar'].type = docstring.MultiType(
{'foo', 'bar'}, )
return expected_func_defaults
def expected_class_of_primitives():
# NOTE the same object is used in both attr and args, this is desirable from
# docstr linking.
name_doc = docstring.ArgDoc(
'name',
str,
'The name associated with the object instance.',
)
z_doc = docstring.ArgDoc(
'z',
float,
'An example of an attribute with a default value, typically set in init.',
3.14159,
)
ok_doc = docstring.ArgDoc(
'ok',
bool,
"""A bool attribute test for configargparse. There were issues before in
the prototype where any non-empty str input including "False" and
"True" were cast to True, whether in config or cli args.""",
False,
)
# NOTE That here, int_float is shorthand, and the objects won't be the same
# in the actual parsed docstring.
int_float = docstring.MultiType({int, float})
return docstring.ClassDocstring(
examples.NumpyDocClass,
"""This is an example class with Numpy docstrings. Short description ends.
This is the beginning of the long descriptions, which can essentially be
arbitrary text until the next section/field occurs.
# TODO include MathTex/LaTeX math here to ensure parsing works with it.
I don't think I can use the $ character to delimit docstr linking as
MathTex may use it! So I need to ensure the character I use is commonly NOT
used by other things wrt docstrings. Perhaps I could just use the markdown
for hyperlinking, but use some indication of namespace / within code
linking.
# TODO Include example of hyperlinking in long description""",
attributes=OrderedDict(
name=name_doc,
a_plus_b=docstring.ArgDoc(
'a_plus_b',
int_float,
"""The addition of two given numbers upon initialization. This also
includes the allowance of two types of int and float.""",
),
x_times_y=docstring.ArgDoc(
'x_times_y',
float,
"""The multiplication of two given numbers upon initialization.
# TODO include markdown for LaTeX Math here as a test case of parsing.""",
),
c=docstring.ArgDoc(
'c',
int,
'Number set upon initialization that increments as foo is used.',
0,
),
z=z_doc,
ok=ok_doc,
),
init=docstring.FuncDocstring(
examples.NumpyDocClass.__init__,
args=OrderedDict(
name=name_doc,
a=docstring.ArgDoc(
'a',
int_float,
'First number in summation.',
),
b=docstring.ArgDoc(
'b',
int_float,
'Second number in summation.',
),
x=docstring.ArgDoc(
'x',
int_float,
'First number in multiplication.',
8,
),
y=docstring.ArgDoc(
'y',
int_float,
"""Second number in multiplication. This is an example of alternative
specification of default. This support is included in order to be
more inclusive of pre-existing standards used by others so that
docstr could be applied to these cases. Docstr is intended to allow
modifcation to their parsing regexes such that custom support for
niche user cases may be handled by the user.""",
11,
),
z=z_doc,
ok=ok_doc,
),
),
# TODO default ignore?, ignore properties, allow skip_missing_doc
)