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 )