1 # -*- coding: utf-8 -*- |
|
2 """ |
|
3 sphinx.ext.autodoc |
|
4 ~~~~~~~~~~~~~~~~~~ |
|
5 |
|
6 Automatically insert docstrings for functions, classes or whole modules into |
|
7 the doctree, thus avoiding duplication between docstrings and documentation |
|
8 for those who like elaborate docstrings. |
|
9 |
|
10 :copyright: 2008 by Georg Brandl, Pauli Virtanen, Martin Hans. |
|
11 :license: BSD. |
|
12 """ |
|
13 |
|
14 import re |
|
15 import sys |
|
16 import types |
|
17 import inspect |
|
18 import linecache |
|
19 from types import FunctionType, BuiltinMethodType, MethodType |
|
20 |
|
21 from docutils import nodes |
|
22 from docutils.parsers.rst import directives |
|
23 from docutils.statemachine import ViewList |
|
24 |
|
25 from sphinx.util import rpartition, nested_parse_with_titles |
|
26 from sphinx.directives.desc import py_sig_re |
|
27 |
|
28 try: |
|
29 base_exception = BaseException |
|
30 except NameError: |
|
31 base_exception = Exception |
|
32 |
|
33 _charset_re = re.compile(r'coding[:=]\s*([-\w.]+)') |
|
34 _module_charsets = {} |
|
35 |
|
36 |
|
37 class Options(object): |
|
38 pass |
|
39 |
|
40 |
|
41 def is_static_method(obj): |
|
42 """Check if the object given is a static method.""" |
|
43 if isinstance(obj, (FunctionType, classmethod)): |
|
44 return True |
|
45 elif isinstance(obj, BuiltinMethodType): |
|
46 return obj.__self__ is not None |
|
47 elif isinstance(obj, MethodType): |
|
48 return obj.im_self is not None |
|
49 return False |
|
50 |
|
51 |
|
52 class AutodocReporter(object): |
|
53 """ |
|
54 A reporter replacement that assigns the correct source name |
|
55 and line number to a system message, as recorded in a ViewList. |
|
56 """ |
|
57 def __init__(self, viewlist, reporter): |
|
58 self.viewlist = viewlist |
|
59 self.reporter = reporter |
|
60 |
|
61 def __getattr__(self, name): |
|
62 return getattr(self.reporter, name) |
|
63 |
|
64 def system_message(self, level, message, *children, **kwargs): |
|
65 if 'line' in kwargs: |
|
66 try: |
|
67 source, line = self.viewlist.items[kwargs['line']] |
|
68 except IndexError: |
|
69 pass |
|
70 else: |
|
71 kwargs['source'] = source |
|
72 kwargs['line'] = line |
|
73 return self.reporter.system_message(level, message, |
|
74 *children, **kwargs) |
|
75 |
|
76 def debug(self, *args, **kwargs): |
|
77 if self.reporter.debug_flag: |
|
78 return self.system_message(0, *args, **kwargs) |
|
79 |
|
80 def info(self, *args, **kwargs): |
|
81 return self.system_message(1, *args, **kwargs) |
|
82 |
|
83 def warning(self, *args, **kwargs): |
|
84 return self.system_message(2, *args, **kwargs) |
|
85 |
|
86 def error(self, *args, **kwargs): |
|
87 return self.system_message(3, *args, **kwargs) |
|
88 |
|
89 def severe(self, *args, **kwargs): |
|
90 return self.system_message(4, *args, **kwargs) |
|
91 |
|
92 |
|
93 # Some useful event listener factories for autodoc-process-docstring. |
|
94 |
|
95 def cut_lines(pre, post=0, what=None): |
|
96 """ |
|
97 Return a listener that removes the first *pre* and last *post* |
|
98 lines of every docstring. If *what* is a sequence of strings, |
|
99 only docstrings of a type in *what* will be processed. |
|
100 |
|
101 Use like this (e.g. in the ``setup()`` function of :file:`conf.py`):: |
|
102 |
|
103 from sphinx.ext.autodoc import cut_lines |
|
104 app.connect('autodoc-process-docstring', cut_lines(4, what=['module'])) |
|
105 |
|
106 This can (and should) be used in place of :confval:`automodule_skip_lines`. |
|
107 """ |
|
108 def process(app, what_, name, obj, options, lines): |
|
109 if what and what_ not in what: |
|
110 return |
|
111 del lines[:pre] |
|
112 if post: |
|
113 # remove one trailing blank line. |
|
114 if lines and not lines[-1]: |
|
115 lines.pop(-1) |
|
116 del lines[-post:] |
|
117 # make sure there is a blank line at the end |
|
118 if lines and lines[-1]: |
|
119 lines.append('') |
|
120 return process |
|
121 |
|
122 def between(marker, what=None, keepempty=False): |
|
123 """ |
|
124 Return a listener that only keeps lines between lines that match the |
|
125 *marker* regular expression. If no line matches, the resulting docstring |
|
126 would be empty, so no change will be made unless *keepempty* is true. |
|
127 |
|
128 If *what* is a sequence of strings, only docstrings of a type in *what* will |
|
129 be processed. |
|
130 """ |
|
131 marker_re = re.compile(marker) |
|
132 def process(app, what_, name, obj, options, lines): |
|
133 if what and what_ not in what: |
|
134 return |
|
135 deleted = 0 |
|
136 delete = True |
|
137 orig_lines = lines[:] |
|
138 for i, line in enumerate(orig_lines): |
|
139 if delete: |
|
140 lines.pop(i - deleted) |
|
141 deleted += 1 |
|
142 if marker_re.match(line): |
|
143 delete = not delete |
|
144 if delete: |
|
145 lines.pop(i - deleted) |
|
146 deleted += 1 |
|
147 if not lines and not keepempty: |
|
148 lines[:] = orig_lines |
|
149 # make sure there is a blank line at the end |
|
150 if lines and lines[-1]: |
|
151 lines.append('') |
|
152 return process |
|
153 |
|
154 |
|
155 def isdescriptor(x): |
|
156 """Check if the object is some kind of descriptor.""" |
|
157 for item in '__get__', '__set__', '__delete__': |
|
158 if callable(getattr(x, item, None)): |
|
159 return True |
|
160 return False |
|
161 |
|
162 |
|
163 def prepare_docstring(s): |
|
164 """ |
|
165 Convert a docstring into lines of parseable reST. Return it as a list of |
|
166 lines usable for inserting into a docutils ViewList (used as argument |
|
167 of nested_parse().) An empty line is added to act as a separator between |
|
168 this docstring and following content. |
|
169 """ |
|
170 lines = s.expandtabs().splitlines() |
|
171 # Find minimum indentation of any non-blank lines after first line. |
|
172 margin = sys.maxint |
|
173 for line in lines[1:]: |
|
174 content = len(line.lstrip()) |
|
175 if content: |
|
176 indent = len(line) - content |
|
177 margin = min(margin, indent) |
|
178 # Remove indentation. |
|
179 if lines: |
|
180 lines[0] = lines[0].lstrip() |
|
181 if margin < sys.maxint: |
|
182 for i in range(1, len(lines)): lines[i] = lines[i][margin:] |
|
183 # Remove any leading blank lines. |
|
184 while lines and not lines[0]: |
|
185 lines.pop(0) |
|
186 # make sure there is an empty line at the end |
|
187 if lines and lines[-1]: |
|
188 lines.append('') |
|
189 return lines |
|
190 |
|
191 |
|
192 def get_module_charset(module): |
|
193 """Return the charset of the given module (cached in _module_charsets).""" |
|
194 if module in _module_charsets: |
|
195 return _module_charsets[module] |
|
196 try: |
|
197 filename = __import__(module, None, None, ['foo']).__file__ |
|
198 except (ImportError, AttributeError): |
|
199 return None |
|
200 if filename[-4:].lower() in ('.pyc', '.pyo'): |
|
201 filename = filename[:-1] |
|
202 for line in [linecache.getline(filename, x) for x in (1, 2)]: |
|
203 match = _charset_re.search(line) |
|
204 if match is not None: |
|
205 charset = match.group(1) |
|
206 break |
|
207 else: |
|
208 charset = 'ascii' |
|
209 _module_charsets[module] = charset |
|
210 return charset |
|
211 |
|
212 |
|
213 class RstGenerator(object): |
|
214 def __init__(self, options, document, lineno): |
|
215 self.options = options |
|
216 self.env = document.settings.env |
|
217 self.reporter = document.reporter |
|
218 self.lineno = lineno |
|
219 self.filename_set = set() |
|
220 self.warnings = [] |
|
221 self.result = ViewList() |
|
222 |
|
223 def warn(self, msg): |
|
224 self.warnings.append(self.reporter.warning(msg, line=self.lineno)) |
|
225 |
|
226 def get_doc(self, what, name, obj): |
|
227 """Format and yield lines of the docstring(s) for the object.""" |
|
228 docstrings = [] |
|
229 if getattr(obj, '__doc__', None): |
|
230 docstrings.append(obj.__doc__) |
|
231 # skip some lines in module docstrings if configured |
|
232 if what == 'module' and self.env.config.automodule_skip_lines and docstrings: |
|
233 docstrings[0] = '\n'.join(docstrings[0].splitlines() |
|
234 [self.env.config.automodule_skip_lines:]) |
|
235 # for classes, what the "docstring" is can be controlled via an option |
|
236 if what in ('class', 'exception'): |
|
237 content = self.env.config.autoclass_content |
|
238 if content in ('both', 'init'): |
|
239 initdocstring = getattr(obj, '__init__', None).__doc__ |
|
240 # for new-style classes, no __init__ means default __init__ |
|
241 if initdocstring == object.__init__.__doc__: |
|
242 initdocstring = None |
|
243 if initdocstring: |
|
244 if content == 'init': |
|
245 docstrings = [initdocstring] |
|
246 else: |
|
247 docstrings.append(initdocstring) |
|
248 # the default is only the class docstring |
|
249 |
|
250 # decode the docstrings using the module's source encoding |
|
251 charset = None |
|
252 module = getattr(obj, '__module__', None) |
|
253 if module is not None: |
|
254 charset = get_module_charset(module) |
|
255 |
|
256 for docstring in docstrings: |
|
257 if isinstance(docstring, str): |
|
258 if charset: |
|
259 docstring = docstring.decode(charset) |
|
260 else: |
|
261 try: |
|
262 # try decoding with utf-8, should only work for real UTF-8 |
|
263 docstring = docstring.decode('utf-8') |
|
264 except UnicodeError: |
|
265 # last resort -- can't fail |
|
266 docstring = docstring.decode('latin1') |
|
267 docstringlines = prepare_docstring(docstring) |
|
268 if self.env.app: |
|
269 # let extensions preprocess docstrings |
|
270 self.env.app.emit('autodoc-process-docstring', |
|
271 what, name, obj, self.options, docstringlines) |
|
272 for line in docstringlines: |
|
273 yield line |
|
274 |
|
275 def resolve_name(self, what, name): |
|
276 """ |
|
277 Determine what module to import and what attribute to document. |
|
278 |
|
279 Returns a tuple of: the full name, the module name, a path of |
|
280 names to get via getattr, the signature and return annotation. |
|
281 """ |
|
282 # first, parse the definition -- auto directives for classes and functions |
|
283 # can contain a signature which is then used instead of an autogenerated one |
|
284 try: |
|
285 path, base, args, retann = py_sig_re.match(name).groups() |
|
286 except: |
|
287 self.warn('invalid signature for auto%s (%r)' % (what, name)) |
|
288 return |
|
289 # fullname is the fully qualified name, base the name after the last dot |
|
290 fullname = (path or '') + base |
|
291 |
|
292 if what == 'module': |
|
293 if args or retann: |
|
294 self.warn('ignoring signature arguments and return annotation ' |
|
295 'for automodule %s' % fullname) |
|
296 return fullname, fullname, [], None, None |
|
297 |
|
298 elif what in ('class', 'exception', 'function'): |
|
299 if path: |
|
300 mod = path.rstrip('.') |
|
301 else: |
|
302 mod = None |
|
303 # if documenting a toplevel object without explicit module, it can |
|
304 # be contained in another auto directive ... |
|
305 if hasattr(self.env, 'autodoc_current_module'): |
|
306 mod = self.env.autodoc_current_module |
|
307 # ... or in the scope of a module directive |
|
308 if not mod: |
|
309 mod = self.env.currmodule |
|
310 return fullname, mod, [base], args, retann |
|
311 |
|
312 else: |
|
313 if path: |
|
314 mod_cls = path.rstrip('.') |
|
315 else: |
|
316 mod_cls = None |
|
317 # if documenting a class-level object without path, there must be a |
|
318 # current class, either from a parent auto directive ... |
|
319 if hasattr(self.env, 'autodoc_current_class'): |
|
320 mod_cls = self.env.autodoc_current_class |
|
321 # ... or from a class directive |
|
322 if mod_cls is None: |
|
323 mod_cls = self.env.currclass |
|
324 # ... if still None, there's no way to know |
|
325 if mod_cls is None: |
|
326 return fullname, None, [], args, retann |
|
327 mod, cls = rpartition(mod_cls, '.') |
|
328 # if the module name is still missing, get it like above |
|
329 if not mod and hasattr(self.env, 'autodoc_current_module'): |
|
330 mod = self.env.autodoc_current_module |
|
331 if not mod: |
|
332 mod = self.env.currmodule |
|
333 return fullname, mod, [cls, base], args, retann |
|
334 |
|
335 def format_signature(self, what, name, obj, args, retann): |
|
336 """ |
|
337 Return the signature of the object, formatted for display. |
|
338 """ |
|
339 if what not in ('class', 'method', 'function'): |
|
340 return '' |
|
341 |
|
342 err = None |
|
343 if args is not None: |
|
344 # signature given explicitly |
|
345 args = "(%s)" % args |
|
346 else: |
|
347 # try to introspect the signature |
|
348 try: |
|
349 args = None |
|
350 getargs = True |
|
351 if what == 'class': |
|
352 # for classes, the relevant signature is the __init__ method's |
|
353 obj = getattr(obj, '__init__', None) |
|
354 # classes without __init__ method, default __init__ or |
|
355 # __init__ written in C? |
|
356 if obj is None or obj is object.__init__ or not \ |
|
357 (inspect.ismethod(obj) or inspect.isfunction(obj)): |
|
358 getargs = False |
|
359 elif inspect.isbuiltin(obj) or inspect.ismethoddescriptor(obj): |
|
360 # can never get arguments of a C function or method |
|
361 getargs = False |
|
362 if getargs: |
|
363 argspec = inspect.getargspec(obj) |
|
364 if what in ('class', 'method') and argspec[0] and \ |
|
365 argspec[0][0] in ('cls', 'self'): |
|
366 del argspec[0][0] |
|
367 args = inspect.formatargspec(*argspec) |
|
368 except Exception, e: |
|
369 args = None |
|
370 err = e |
|
371 |
|
372 result = self.env.app.emit_firstresult('autodoc-process-signature', what, |
|
373 name, obj, self.options, args, retann) |
|
374 if result: |
|
375 args, retann = result |
|
376 |
|
377 if args is not None: |
|
378 return '%s%s' % (args, retann or '') |
|
379 elif err: |
|
380 # re-raise the error for perusal of the handler in generate() |
|
381 raise RuntimeError(err) |
|
382 else: |
|
383 return '' |
|
384 |
|
385 def generate(self, what, name, members, add_content, indent=u'', check_module=False): |
|
386 """ |
|
387 Generate reST for the object in self.result. |
|
388 """ |
|
389 fullname, mod, objpath, args, retann = self.resolve_name(what, name) |
|
390 if not mod: |
|
391 # need a module to import |
|
392 self.warn('don\'t know which module to import for autodocumenting %r ' |
|
393 '(try placing a "module" or "currentmodule" directive in the ' |
|
394 'document, or giving an explicit module name)' % fullname) |
|
395 return |
|
396 |
|
397 # the name to put into the generated directive -- doesn't contain the module |
|
398 name_in_directive = '.'.join(objpath) or mod |
|
399 |
|
400 # now, import the module and get object to document |
|
401 try: |
|
402 todoc = module = __import__(mod, None, None, ['foo']) |
|
403 if hasattr(module, '__file__') and module.__file__: |
|
404 modfile = module.__file__ |
|
405 if modfile[-4:].lower() in ('.pyc', '.pyo'): |
|
406 modfile = modfile[:-1] |
|
407 self.filename_set.add(modfile) |
|
408 else: |
|
409 modfile = None # e.g. for builtin and C modules |
|
410 for part in objpath: |
|
411 todoc = getattr(todoc, part) |
|
412 except (ImportError, AttributeError), err: |
|
413 self.warn('autodoc can\'t import/find %s %r, it reported error: "%s", ' |
|
414 'please check your spelling and sys.path' % |
|
415 (what, str(fullname), err)) |
|
416 return |
|
417 |
|
418 # check __module__ of object if wanted (for members not given explicitly) |
|
419 if check_module: |
|
420 if hasattr(todoc, '__module__'): |
|
421 if todoc.__module__ != mod: |
|
422 return |
|
423 |
|
424 # format the object's signature, if any |
|
425 try: |
|
426 sig = self.format_signature(what, name, todoc, args, retann) |
|
427 except Exception, err: |
|
428 self.warn('error while formatting signature for %s: %s' % |
|
429 (fullname, err)) |
|
430 sig = '' |
|
431 |
|
432 # make sure that the result starts with an empty line. This is |
|
433 # necessary for some situations where another directive preprocesses |
|
434 # reST and no starting newline is present |
|
435 self.result.append(u'', '') |
|
436 |
|
437 # now, create the directive header |
|
438 directive = (what == 'method' and is_static_method(todoc)) \ |
|
439 and 'staticmethod' or what |
|
440 self.result.append(indent + u'.. %s:: %s%s' % |
|
441 (directive, name_in_directive, sig), '<autodoc>') |
|
442 if what == 'module': |
|
443 # Add some module-specific options |
|
444 if self.options.synopsis: |
|
445 self.result.append(indent + u' :synopsis: ' + self.options.synopsis, |
|
446 '<autodoc>') |
|
447 if self.options.platform: |
|
448 self.result.append(indent + u' :platform: ' + self.options.platform, |
|
449 '<autodoc>') |
|
450 if self.options.deprecated: |
|
451 self.result.append(indent + u' :deprecated:', '<autodoc>') |
|
452 else: |
|
453 # Be explicit about the module, this is necessary since .. class:: doesn't |
|
454 # support a prepended module name |
|
455 self.result.append(indent + u' :module: %s' % mod, '<autodoc>') |
|
456 if self.options.noindex: |
|
457 self.result.append(indent + u' :noindex:', '<autodoc>') |
|
458 self.result.append(u'', '<autodoc>') |
|
459 |
|
460 if self.options.show_inheritance and what in ('class', 'exception'): |
|
461 if len(todoc.__bases__): |
|
462 bases = [b.__module__ == '__builtin__' and |
|
463 u':class:`%s`' % b.__name__ or |
|
464 u':class:`%s.%s`' % (b.__module__, b.__name__) |
|
465 for b in todoc.__bases__] |
|
466 self.result.append(indent + u' Bases: %s' % ', '.join(bases), |
|
467 '<autodoc>') |
|
468 self.result.append(u'', '<autodoc>') |
|
469 |
|
470 # the module directive doesn't have content |
|
471 if what != 'module': |
|
472 indent += u' ' |
|
473 |
|
474 if modfile: |
|
475 sourcename = '%s:docstring of %s' % (modfile, fullname) |
|
476 else: |
|
477 sourcename = 'docstring of %s' % fullname |
|
478 |
|
479 # add content from docstrings |
|
480 for i, line in enumerate(self.get_doc(what, fullname, todoc)): |
|
481 self.result.append(indent + line, sourcename, i) |
|
482 |
|
483 # add source content, if present |
|
484 if add_content: |
|
485 for line, src in zip(add_content.data, add_content.items): |
|
486 self.result.append(indent + line, src[0], src[1]) |
|
487 |
|
488 # document members? |
|
489 if not members or what in ('function', 'method', 'attribute'): |
|
490 return |
|
491 |
|
492 # set current namespace for finding members |
|
493 self.env.autodoc_current_module = mod |
|
494 if objpath: |
|
495 self.env.autodoc_current_class = objpath[0] |
|
496 |
|
497 # add members, if possible |
|
498 _all = members == ['__all__'] |
|
499 members_check_module = False |
|
500 if _all: |
|
501 # unqualified :members: given |
|
502 if what == 'module': |
|
503 if hasattr(todoc, '__all__'): |
|
504 members_check_module = False |
|
505 all_members = [] |
|
506 for mname in todoc.__all__: |
|
507 try: |
|
508 all_members.append((mname, getattr(todoc, mname))) |
|
509 except AttributeError: |
|
510 self.warn('missing attribute mentioned in __all__: ' |
|
511 'module %s, attribute %s' % |
|
512 (todoc.__name__, mname)) |
|
513 else: |
|
514 # for implicit module members, check __module__ to avoid |
|
515 # documenting imported objects |
|
516 members_check_module = True |
|
517 all_members = inspect.getmembers(todoc) |
|
518 else: |
|
519 if self.options.inherited_members: |
|
520 # getmembers() uses dir() which pulls in members from all |
|
521 # base classes |
|
522 all_members = inspect.getmembers(todoc) |
|
523 else: |
|
524 # __dict__ contains only the members directly defined in the class |
|
525 all_members = sorted(todoc.__dict__.iteritems()) |
|
526 else: |
|
527 all_members = [(mname, getattr(todoc, mname)) for mname in members] |
|
528 for (membername, member) in all_members: |
|
529 # ignore members whose name starts with _ by default |
|
530 if _all and membername.startswith('_'): |
|
531 continue |
|
532 |
|
533 # ignore undocumented members if :undoc-members: is not given |
|
534 doc = getattr(member, '__doc__', None) |
|
535 skip = not self.options.undoc_members and not doc |
|
536 # give the user a chance to decide whether this member should be skipped |
|
537 if self.env.app: |
|
538 # let extensions preprocess docstrings |
|
539 skip_user = self.env.app.emit_firstresult( |
|
540 'autodoc-skip-member', what, membername, member, skip, self.options) |
|
541 if skip_user is not None: |
|
542 skip = skip_user |
|
543 if skip: |
|
544 continue |
|
545 |
|
546 if what == 'module': |
|
547 if isinstance(member, (types.FunctionType, |
|
548 types.BuiltinFunctionType)): |
|
549 memberwhat = 'function' |
|
550 elif isinstance(member, types.ClassType) or \ |
|
551 isinstance(member, type): |
|
552 if issubclass(member, base_exception): |
|
553 memberwhat = 'exception' |
|
554 else: |
|
555 memberwhat = 'class' |
|
556 else: |
|
557 # XXX: todo -- attribute docs |
|
558 continue |
|
559 else: |
|
560 if callable(member): |
|
561 memberwhat = 'method' |
|
562 elif isdescriptor(member): |
|
563 memberwhat = 'attribute' |
|
564 else: |
|
565 # XXX: todo -- attribute docs |
|
566 continue |
|
567 full_membername = fullname + '.' + membername |
|
568 self.generate(memberwhat, full_membername, ['__all__'], None, indent, |
|
569 check_module=members_check_module) |
|
570 |
|
571 self.env.autodoc_current_module = None |
|
572 self.env.autodoc_current_class = None |
|
573 |
|
574 |
|
575 def _auto_directive(dirname, arguments, options, content, lineno, |
|
576 content_offset, block_text, state, state_machine): |
|
577 what = dirname[4:] # strip "auto" |
|
578 name = arguments[0] |
|
579 genopt = Options() |
|
580 members = options.get('members', []) |
|
581 genopt.inherited_members = 'inherited-members' in options |
|
582 if genopt.inherited_members and not members: |
|
583 # :inherited-members: implies :members: |
|
584 members = ['__all__'] |
|
585 genopt.undoc_members = 'undoc-members' in options |
|
586 genopt.show_inheritance = 'show-inheritance' in options |
|
587 genopt.noindex = 'noindex' in options |
|
588 genopt.synopsis = options.get('synopsis', '') |
|
589 genopt.platform = options.get('platform', '') |
|
590 genopt.deprecated = 'deprecated' in options |
|
591 |
|
592 generator = RstGenerator(genopt, state.document, lineno) |
|
593 generator.generate(what, name, members, content) |
|
594 if not generator.result: |
|
595 return generator.warnings |
|
596 |
|
597 # record all filenames as dependencies -- this will at least partially make |
|
598 # automatic invalidation possible |
|
599 for fn in generator.filename_set: |
|
600 state.document.settings.env.note_dependency(fn) |
|
601 |
|
602 # use a custom reporter that correctly assigns lines to source and lineno |
|
603 old_reporter = state.memo.reporter |
|
604 state.memo.reporter = AutodocReporter(generator.result, state.memo.reporter) |
|
605 if dirname == 'automodule': |
|
606 node = nodes.section() |
|
607 nested_parse_with_titles(state, generator.result, node) |
|
608 else: |
|
609 node = nodes.paragraph() |
|
610 state.nested_parse(generator.result, 0, node) |
|
611 state.memo.reporter = old_reporter |
|
612 return generator.warnings + node.children |
|
613 |
|
614 def auto_directive(*args, **kwds): |
|
615 return _auto_directive(*args, **kwds) |
|
616 |
|
617 def automodule_directive(*args, **kwds): |
|
618 return _auto_directive(*args, **kwds) |
|
619 |
|
620 def autoclass_directive(*args, **kwds): |
|
621 return _auto_directive(*args, **kwds) |
|
622 |
|
623 |
|
624 def members_option(arg): |
|
625 if arg is None: |
|
626 return ['__all__'] |
|
627 return [x.strip() for x in arg.split(',')] |
|
628 |
|
629 |
|
630 def setup(app): |
|
631 mod_options = {'members': members_option, 'undoc-members': directives.flag, |
|
632 'noindex': directives.flag, 'inherited-members': directives.flag, |
|
633 'show-inheritance': directives.flag, 'synopsis': lambda x: x, |
|
634 'platform': lambda x: x, 'deprecated': directives.flag} |
|
635 cls_options = {'members': members_option, 'undoc-members': directives.flag, |
|
636 'noindex': directives.flag, 'inherited-members': directives.flag, |
|
637 'show-inheritance': directives.flag} |
|
638 app.add_directive('automodule', automodule_directive, |
|
639 1, (1, 0, 1), **mod_options) |
|
640 app.add_directive('autoclass', autoclass_directive, |
|
641 1, (1, 0, 1), **cls_options) |
|
642 app.add_directive('autoexception', autoclass_directive, |
|
643 1, (1, 0, 1), **cls_options) |
|
644 app.add_directive('autofunction', auto_directive, 1, (1, 0, 1), |
|
645 noindex=directives.flag) |
|
646 app.add_directive('automethod', auto_directive, 1, (1, 0, 1), |
|
647 noindex=directives.flag) |
|
648 app.add_directive('autoattribute', auto_directive, 1, (1, 0, 1), |
|
649 noindex=directives.flag) |
|
650 # deprecated: remove in some future version. |
|
651 app.add_config_value('automodule_skip_lines', 0, True) |
|
652 app.add_config_value('autoclass_content', 'class', True) |
|
653 app.add_event('autodoc-process-docstring') |
|
654 app.add_event('autodoc-process-signature') |
|
655 app.add_event('autodoc-skip-member') |
|