def expected_recursive_parse(
expected_func,
expected_func_defaults,
expected_func_choices,
):
"""Example of recursive parsing as seen in a run or main function."""
return docstring.FuncDocstring(
examples.func_recursive_parse,
'An example of recursive parsing of types for a run or main function.',
args=OrderedDict(
identifier=docstring.ArgDoc(
'identifier',
str,
'String identifier for this run.',
),
func_1=docstring.ArgDoc(
'func_1',
expected_func,
'The first function to be executed.',
),
func_2=docstring.ArgDoc(
'func_2',
expected_func_defaults,
'The second function to be executed.',
),
func_3=docstring.ArgDoc(
'func_3',
expected_func_choices,
'The third function to be executed.',
),
),
)
def expected_class_recursive_parse():
args = OrderedDict(
very_useful_class=docstring.ArgDoc(
'very_useful_class',
examples.NumpyDocClass,
'Truly, a very useful class instance.',
),
func_2=docstring.ArgDoc(
'func_2',
Callable,
"A function to be called throughout the class' use.",
examples.func_defaults,
),
)
return docstring.ClassDocstring(
examples.NumpyDocClassRecursiveParse,
'A class with objects to be parsed.',
attributes=args,
init=docstring.FuncDocstring(
examples.NumpyDocClassRecursiveParse.__init__,
"""I have a description, unlike NumpyDocClass, but whatever really.
I also support see self shorthand for all attributes are args, as
expected of see namespace.path.to.object.""",
args=args,
),
)
def expected_class_of_primitives_methods(expected_class_of_primitives):
expected_class_of_primitives.methods=dict(
foo=docstring.FuncDocstring(
examples.NumpyDocClass.foo,
"""The foo function performs Tom foo-ery. Heh heh.
However the long description of foo() is longer than the short
description but still not too long to be cumbersome.
Perhaps it can be too long and that's alright because it is the long
description. The long description can be as long as it wants or as
short as it wants; even non-existent.""",
args=OrderedDict(
oh=docstring.ArgDoc(
'oh',
str,
'First word in the paired concatenation of string inputs.',
),
my=docstring.ArgDoc(
'my',
str,
'Second word in the paired concatenation of string inputs.',
),
),
returns=docstring.BaseDoc(
'returns',
str,
'Concatenate oh and my in that order.',
),
),
)
return expected_class_of_primitives
def expected_func():
return docstring.FuncDocstring(
examples.func,
'This is the short desc. of the function, concat the paired strings',
args=OrderedDict(
foo=docstring.ArgDoc(
'foo',
str,
'Foo is an excellently documented string argument.',
),
bar=docstring.ArgDoc(
'bar',
str,
'Bar is an excellently documented string argument.',
)),
returns=docstring.BaseDoc(
'returns',
str,
'An incredible ordered concatenation of the paired string inputs.',
))
def expected_class_linking(expected_class_of_primitives):
expected_class_of_primitives.attributes.update(
example_var=docstring.ArgDoc('example_var', object),
is_this_correct=docstring.ArgDoc(
'is_this_correct',
bool,
default=False,
),
)
expected_class_of_primitives.methods.update(
bar=docstring.FuncDocstring(
examples.NumpyDocClassLinking.bar,
'Same args as foo, but performs a different operation.',
args=expected_class_of_primitives.methods['foo'].args
)
)
return docstring.ClassDocstring(
examples.NumpyDocClassLinking,
'A Numpy example class that uses docstring linking.',
attributes=expected_class_of_primitives.attributes,
init=None,
methods=expected_class_of_primitives.methods,
)
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
)