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
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
|
import inspect
import pydoc
import re
import textwrap
from sphinx.pycode import ModuleAnalyzer
from .docscrape import ClassDoc, FunctionDoc, NumpyDocString
class SphinxDocString(NumpyDocString):
def __init__(self, docstring, config=None):
if config is None:
config = {}
NumpyDocString.__init__(self, docstring, config=config)
# string conversion routines
@staticmethod
def _str_header(name, symbol="`"):
return [f".. rubric:: {name}", ""]
@staticmethod
def _str_field_list(name):
return [f":{name}:"]
@staticmethod
def _str_indent(doc, indent=4):
out = []
for line in doc:
out += [" " * indent + line]
return out
def _str_summary(self):
return self["Summary"] + [""]
def _str_extended_summary(self):
return self["Extended Summary"] + [""]
def _str_param_list(self, name):
out = []
if self[name]:
out += self._str_field_list(name)
out += [""]
for param, param_type, desc in self[name]:
out += self._str_indent([f"**{param.strip()}** : {param_type}"])
out += [""]
out += self._str_indent(desc, 8)
out += [""]
return out
@property
def _obj(self):
if hasattr(self, "_cls"):
return self._cls
elif hasattr(self, "_f"):
return self._f
return None
def _str_member_list(self):
"""
Generate a member listing, autosummary:: table .
"""
out = []
for name in ["Attributes", "Methods"]:
if not self[name]:
continue
out += [f".. rubric:: {name}", ""]
prefix = getattr(self, "_name", "")
if prefix:
prefix = f"{prefix}."
autosum = []
for param, _, desc in self[name]:
param = param.strip()
if self._obj:
# Fake the attribute as a class property, but do not touch
# methods
if hasattr(self._obj, "__module__") and not (
hasattr(self._obj, param)
and callable(getattr(self._obj, param))
):
# Do not override directly provided docstrings
if not len("".join(desc).strip()):
analyzer = ModuleAnalyzer.for_module(self._obj.__module__)
desc = analyzer.find_attr_docs().get(
(self._obj.__name__, param), ""
)
# Only fake a property if we got a docstring
if len("".join(desc).strip()):
setattr(
self._obj,
param,
property(lambda self: None, doc="\n".join(desc)),
)
if len(prefix):
autosum += [f" ~{prefix}{param}"]
else:
autosum += [f" {param}"]
if autosum:
out += [".. autosummary::", ""]
out += autosum
out += [""]
return out
def _str_member_docs(self, name):
"""
Generate the full member autodocs
"""
out = []
if self[name]:
prefix = getattr(self, "_name", "")
if prefix:
prefix += "."
for param, _, _ in self[name]:
if name == "Methods":
out += [f".. automethod:: {prefix}{param}"]
elif name == "Attributes":
out += [f".. autoattribute:: {prefix}{param}"]
out += [""]
return out
def _str_section(self, name):
out = []
if self[name]:
out += self._str_header(name)
out += [""]
content = textwrap.dedent("\n".join(self[name])).split("\n")
out += content
out += [""]
return out
def _str_see_also(self, func_role):
out = []
if self["See Also"]:
see_also = super()._str_see_also(func_role)
out = [".. seealso::", ""]
out += self._str_indent(see_also[2:])
return out
def _str_raises(self, name, func_role):
if not self[name]:
return []
out = []
out += self._str_header(name)
for func, _, desc in self[name]:
out += [f":exc:`{func}`"]
if desc:
out += self._str_indent([" ".join(desc)])
out += [""]
return out
def _str_warnings(self):
out = []
if self["Warnings"]:
out = [".. warning::", ""]
out += self._str_indent(self["Warnings"])
return out
def _str_index(self):
idx = self["index"]
out = []
if len(idx) == 0:
return out
out += [f".. index:: {idx.get('default', '')}"]
for section, references in idx.items():
if section == "default":
continue
elif section == "refguide":
out += [f" single: {', '.join(references)}"]
else:
out += [f" {section}: {','.join(references)}"]
return out
def _str_references(self):
out = []
if self["References"]:
out += self._str_header("References")
if isinstance(self["References"], str):
self["References"] = [self["References"]]
out.extend(self["References"])
out += [""]
# Latex collects all references to a separate bibliography,
# so we need to insert links to it
out += [".. only:: latex", ""]
items = []
for line in self["References"]:
m = re.match(r".. \[([a-z0-9._-]+)\]", line, re.I)
if m:
items.append(m.group(1))
out += [f" {', '.join([f'[{item}]_' for item in items])}", ""]
return out
def _str_examples(self):
return self._str_section("Examples")
def __str__(self, indent=0, func_role="brianobj"):
out = []
out += self._str_index() + [""]
out += self._str_summary()
out += self._str_extended_summary()
for param_list in ("Parameters", "Returns", "Other Parameters"):
out += self._str_param_list(param_list)
for param_list in ("Raises", "Warns"):
out += self._str_raises(param_list, func_role)
out += self._str_warnings()
out += self._str_see_also(func_role)
out += self._str_section("Notes")
out += self._str_references()
out += self._str_examples()
out += self._str_member_list()
if self["Attributes"] + self["Methods"]:
out += [".. rubric:: Details", ""]
for param_list in ("Attributes", "Methods"):
out += self._str_member_docs(param_list)
out = self._str_indent(out, indent)
return "\n".join(out)
class SphinxFunctionDoc(SphinxDocString, FunctionDoc):
def __init__(self, obj, doc=None, config=None):
if config is None:
config = {}
FunctionDoc.__init__(self, obj, doc=doc, config=config)
class SphinxClassDoc(SphinxDocString, ClassDoc):
def __init__(self, obj, doc=None, func_doc=None, name=None, config=None):
if config is None:
config = {}
self.name = name
ClassDoc.__init__(self, obj, doc=doc, func_doc=None, config=config)
class SphinxObjDoc(SphinxDocString):
def __init__(self, obj, doc=None, config=None):
if config is None:
config = {}
self._f = obj
SphinxDocString.__init__(self, doc, config=config)
def get_doc_object(obj, what=None, doc=None, name=None, config=None):
if config is None:
config = {}
if what is None:
if inspect.isclass(obj):
what = "class"
elif inspect.ismodule(obj):
what = "module"
elif callable(obj):
what = "function"
else:
what = "object"
if what == "class":
return SphinxClassDoc(
obj, func_doc=SphinxFunctionDoc, doc=doc, name=name, config=config
)
elif what in ("function", "method"):
return SphinxFunctionDoc(obj, doc=doc, config=config)
else:
if doc is None:
doc = pydoc.getdoc(obj)
return SphinxObjDoc(obj, doc, config=config)
|
