DocstringProcessor¶
- class openpnm.utils.misc.DocstringProcessor(*args, **kwargs)[source]¶
Class that is intended to process docstrings.
It is, but only to minor extends, inspired by the
matplotlib.docstring.Substitution
class.Examples
Create docstring processor via:
>>> from docrep import DocstringProcessor >>> d = DocstringProcessor(doc_key='My doc string')
And then use it as a decorator to process the docstring:
>>> @d ... def doc_test(): ... '''That's %(doc_key)s''' ... pass >>> print(doc_test.__doc__) That's My doc string
Use the
get_sections()
method to extract Parameter sections (or others) form the docstring for later usage (and make sure, that the docstring is dedented):>>> @d.get_sections(base='docstring_example', ... sections=['Parameters', 'Examples']) ... @d.dedent ... def doc_test(a=1, b=2): ... ''' ... That's %(doc_key)s ... ... Parameters ... ---------- ... a: int, optional ... A dummy parameter description ... b: int, optional ... A second dummy parameter ... ... Examples ... -------- ... Some dummy example doc''' ... print(a) >>> @d.dedent ... def second_test(a=1, b=2): ... ''' ... My second function where I want to use the docstring from ... above ... ... Parameters ... ---------- ... %(docstring_example.parameters)s ... ... Examples ... -------- ... %(docstring_example.examples)s''' ... pass >>> print(second_test.__doc__) My second function where I want to use the docstring from above Parameters ---------- a: int, optional A dummy parameter description b: int, optional A second dummy parameter Examples -------- Some dummy example doc
Another example uses non-dedented docstrings:
>>> @d.get_sections(base='not_dedented') ... def doc_test2(a=1): ... '''That's the summary ... ... Parameters ... ---------- ... a: int, optional ... A dummy parameter description''' ... print(a)
These sections must then be used with the
with_indent()
method to indent the inserted parameters:>>> @d.with_indent(4) ... def second_test2(a=1): ... ''' ... My second function where I want to use the docstring from ... above ... ... Parameters ... ---------- ... %(not_dedented.parameters)s''' ... pass
Methods
dedent
(s[, stacklevel])Dedent a string and substitute with the
params
attribute.dedents
(*args, **kwargs)Deprecated method
delete_kwargs
(base_key[, args, kwargs])Delete the
*args
or**kwargs
part from the parameters section.delete_kwargs_s
(*args, **kwargs)Deprecated method
delete_params
(base_key, *params)Delete a parameter from a parameter documentation.
delete_params_s
(*args, **kwargs)Deprecated function
delete_types
(base_key, out_key, *types)Delete a parameter from a parameter documentation.
delete_types_s
(*args, **kwargs)Deprecated function
get_docstring
(s[, base])Get a docstring of a function.
get_extended_summary
(s[, base])Get the extended summary from a docstring.
get_extended_summaryf
(*args, **kwargs)Deprecated method
get_full_description
(s[, base])Get the full description from a docstring.
get_full_descriptionf
(*args, **kwargs)Deprecated method
get_sections
(s[, base, sections])Exctract sections out of a docstring.
get_sectionsf
(*args, **kwargs)Deprecated method
get_summary
(s[, base])Get the summary of the given docstring.
get_summaryf
(*args, **kwargs)Deprecated method
keep_params
(base_key, *params)Keep only specific parameters from a parameter documentation.
keep_params_s
(*args, **kwargs)Deprecated function
keep_types
(base_key, out_key, *types)Keep only specific parameters from a parameter documentation.
keep_types_s
(*args, **kwargs)Deprecated function
save_docstring
(*args, **kwargs)Deprecated method
with_indent
(s[, indent, stacklevel])Substitute a string with the indented
params
.with_indents
(*args, **kwargs)Deprecated method