/usr/lib/python3/dist-packages/numpydoc/traitsdoc.py is in python3-numpydoc 0.6.0+ds1-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 | """
=========
traitsdoc
=========
Sphinx extension that handles docstrings in the Numpy standard format, [1]
and support Traits [2].
This extension can be used as a replacement for ``numpydoc`` when support
for Traits is required.
.. [1] http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines#docstring-standard
.. [2] http://code.enthought.com/projects/traits/
"""
from __future__ import division, absolute_import, print_function
import inspect
import os
import pydoc
import collections
from . import docscrape
from . import docscrape_sphinx
from .docscrape_sphinx import SphinxClassDoc, SphinxFunctionDoc, SphinxDocString
from . import numpydoc
from . import comment_eater
class SphinxTraitsDoc(SphinxClassDoc):
def __init__(self, cls, modulename='', func_doc=SphinxFunctionDoc):
if not inspect.isclass(cls):
raise ValueError("Initialise using a class. Got %r" % cls)
self._cls = cls
if modulename and not modulename.endswith('.'):
modulename += '.'
self._mod = modulename
self._name = cls.__name__
self._func_doc = func_doc
docstring = pydoc.getdoc(cls)
docstring = docstring.split('\n')
# De-indent paragraph
try:
indent = min(len(s) - len(s.lstrip()) for s in docstring
if s.strip())
except ValueError:
indent = 0
for n,line in enumerate(docstring):
docstring[n] = docstring[n][indent:]
self._doc = docscrape.Reader(docstring)
self._parsed_data = {
'Signature': '',
'Summary': '',
'Description': [],
'Extended Summary': [],
'Parameters': [],
'Returns': [],
'Yields': [],
'Raises': [],
'Warns': [],
'Other Parameters': [],
'Traits': [],
'Methods': [],
'See Also': [],
'Notes': [],
'References': '',
'Example': '',
'Examples': '',
'index': {}
}
self._parse()
def _str_summary(self):
return self['Summary'] + ['']
def _str_extended_summary(self):
return self['Description'] + self['Extended Summary'] + ['']
def __str__(self, indent=0, func_role="func"):
out = []
out += self._str_signature()
out += self._str_index() + ['']
out += self._str_summary()
out += self._str_extended_summary()
for param_list in ('Parameters', 'Traits', 'Methods',
'Returns', 'Yields', 'Raises'):
out += self._str_param_list(param_list)
out += self._str_see_also("obj")
out += self._str_section('Notes')
out += self._str_references()
out += self._str_section('Example')
out += self._str_section('Examples')
out = self._str_indent(out,indent)
return '\n'.join(out)
def looks_like_issubclass(obj, classname):
""" Return True if the object has a class or superclass with the given class
name.
Ignores old-style classes.
"""
t = obj
if t.__name__ == classname:
return True
for klass in t.__mro__:
if klass.__name__ == classname:
return True
return False
def get_doc_object(obj, what=None, config=None):
if what is None:
if inspect.isclass(obj):
what = 'class'
elif inspect.ismodule(obj):
what = 'module'
elif isinstance(obj, collections.Callable):
what = 'function'
else:
what = 'object'
if what == 'class':
doc = SphinxTraitsDoc(obj, '', func_doc=SphinxFunctionDoc, config=config)
if looks_like_issubclass(obj, 'HasTraits'):
for name, trait, comment in comment_eater.get_class_traits(obj):
# Exclude private traits.
if not name.startswith('_'):
doc['Traits'].append((name, trait, comment.splitlines()))
return doc
elif what in ('function', 'method'):
return SphinxFunctionDoc(obj, '', config=config)
else:
return SphinxDocString(pydoc.getdoc(obj), config=config)
def setup(app):
# init numpydoc
numpydoc.setup(app, get_doc_object)
|