"""Docstring module of the psyplot package
We use the docrep_ package for managing our docstrings
.. _docrep: http://docrep.readthedocs.io/en/latest/
"""
# SPDX-FileCopyrightText: 2016-2024 University of Lausanne
# SPDX-FileCopyrightText: 2020-2021 Helmholtz-Zentrum Geesthacht
# SPDX-FileCopyrightText: 2021-2024 Helmholtz-Zentrum hereon GmbH
#
# SPDX-License-Identifier: LGPL-3.0-only
import inspect
import types
import six
from docrep import DocstringProcessor, safe_modulo # noqa: F401
[docs]
def dedent(func):
"""
Dedent the docstring of a function and substitute with :attr:`params`
Parameters
----------
func: function
function with the documentation to dedent"""
if isinstance(func, types.MethodType) and not six.PY3:
func = func.im_func
func.__doc__ = func.__doc__ and inspect.cleandoc(func.__doc__)
return func
[docs]
def indent(text, num=4):
"""Indet the given string"""
str_indent = " " * num
return str_indent + ("\n" + str_indent).join(text.splitlines())
[docs]
def append_original_doc(parent, num=0):
"""Return an iterator that append the docstring of the given `parent`
function to the applied function"""
def func(func):
func.__doc__ = func.__doc__ and func.__doc__ + indent(
parent.__doc__, num
)
return func
return func
_docstrings = DocstringProcessor()
_docstrings.get_sections(base="DocstringProcessor.get_sections")(
dedent(DocstringProcessor.get_sections)
)
[docs]
class PsyplotDocstringProcessor(DocstringProcessor):
"""
A :class:`docrep.DocstringProcessor` subclass with possible types section
"""
param_like_sections = DocstringProcessor.param_like_sections + [
"Possible types"
]
[docs]
@_docstrings.dedent
def get_sections(
self,
s=None,
base=None,
sections=["Parameters", "Other Parameters", "Possible types"],
):
"""
Extract the specified sections out of the given string
The same as the :meth:`docrep.DocstringProcessor.get_sections` method
but uses the ``'Possible types'`` section by default, too
Parameters
----------
%(DocstringProcessor.get_sections.parameters)s
Returns
-------
str
The replaced string
"""
return super(PsyplotDocstringProcessor, self).get_sections(
s, base, sections
)
del _docstrings
#: :class:`docrep.PsyplotDocstringProcessor` instance that simplifies the reuse
#: of docstrings from between different python objects.
docstrings = PsyplotDocstringProcessor()