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