DocstringProcessor

class openpnm.utils.misc.DocstringProcessor(*args, **kwargs)

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