forked from psyplot/psyplot
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathdocstring.py
More file actions
executable file
·106 lines (83 loc) · 3.23 KB
/
docstring.py
File metadata and controls
executable file
·106 lines (83 loc) · 3.23 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
"""Docstring module of the psyplot package
We use the docrep_ package for managing our docstrings
.. _docrep: http://docrep.readthedocs.io/en/latest/
"""
# Disclaimer
# ----------
#
# Copyright (C) 2021 Helmholtz-Zentrum Hereon
# Copyright (C) 2020-2021 Helmholtz-Zentrum Geesthacht
# Copyright (C) 2016-2021 University of Lausanne
#
# This file is part of psyplot and is released under the GNU LGPL-3.O license.
# See COPYING and COPYING.LESSER in the root of the repository for full
# licensing details.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License version 3.0 as
# published by the Free Software Foundation.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU LGPL-3.0 license for more details.
#
# You should have received a copy of the GNU LGPL-3.0 license
# along with this program. If not, see <https://www.gnu.org/licenses/>.
import types
import six
import inspect
from docrep import DocstringProcessor, safe_modulo
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
def indent(text, num=4):
"""Indet the given string"""
str_indent = ' ' * num
return str_indent + ('\n' + str_indent).join(text.splitlines())
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))
class PsyplotDocstringProcessor(DocstringProcessor):
"""
A :class:`docrep.DocstringProcessor` subclass with possible types section
"""
param_like_sections = DocstringProcessor.param_like_sections + [
'Possible types']
@_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()