mirror of
https://github.com/wassname/scikit-image.git
synced 2026-07-17 11:32:45 +08:00
Add numpy-sphinx docs extensions.
This commit is contained in:
Stefan van der Walt
@@ -0,0 +1,497 @@
|
||||
"""Extract reference documentation from the NumPy source tree.
|
||||
|
||||
"""
|
||||
|
||||
import inspect
|
||||
import textwrap
|
||||
import re
|
||||
import pydoc
|
||||
from StringIO import StringIO
|
||||
from warnings import warn
|
||||
|
||||
class Reader(object):
|
||||
"""A line-based string reader.
|
||||
|
||||
"""
|
||||
def __init__(self, data):
|
||||
"""
|
||||
Parameters
|
||||
----------
|
||||
data : str
|
||||
String with lines separated by '\n'.
|
||||
|
||||
"""
|
||||
if isinstance(data,list):
|
||||
self._str = data
|
||||
else:
|
||||
self._str = data.split('\n') # store string as list of lines
|
||||
|
||||
self.reset()
|
||||
|
||||
def __getitem__(self, n):
|
||||
return self._str[n]
|
||||
|
||||
def reset(self):
|
||||
self._l = 0 # current line nr
|
||||
|
||||
def read(self):
|
||||
if not self.eof():
|
||||
out = self[self._l]
|
||||
self._l += 1
|
||||
return out
|
||||
else:
|
||||
return ''
|
||||
|
||||
def seek_next_non_empty_line(self):
|
||||
for l in self[self._l:]:
|
||||
if l.strip():
|
||||
break
|
||||
else:
|
||||
self._l += 1
|
||||
|
||||
def eof(self):
|
||||
return self._l >= len(self._str)
|
||||
|
||||
def read_to_condition(self, condition_func):
|
||||
start = self._l
|
||||
for line in self[start:]:
|
||||
if condition_func(line):
|
||||
return self[start:self._l]
|
||||
self._l += 1
|
||||
if self.eof():
|
||||
return self[start:self._l+1]
|
||||
return []
|
||||
|
||||
def read_to_next_empty_line(self):
|
||||
self.seek_next_non_empty_line()
|
||||
def is_empty(line):
|
||||
return not line.strip()
|
||||
return self.read_to_condition(is_empty)
|
||||
|
||||
def read_to_next_unindented_line(self):
|
||||
def is_unindented(line):
|
||||
return (line.strip() and (len(line.lstrip()) == len(line)))
|
||||
return self.read_to_condition(is_unindented)
|
||||
|
||||
def peek(self,n=0):
|
||||
if self._l + n < len(self._str):
|
||||
return self[self._l + n]
|
||||
else:
|
||||
return ''
|
||||
|
||||
def is_empty(self):
|
||||
return not ''.join(self._str).strip()
|
||||
|
||||
|
||||
class NumpyDocString(object):
|
||||
def __init__(self,docstring):
|
||||
docstring = textwrap.dedent(docstring).split('\n')
|
||||
|
||||
self._doc = Reader(docstring)
|
||||
self._parsed_data = {
|
||||
'Signature': '',
|
||||
'Summary': [''],
|
||||
'Extended Summary': [],
|
||||
'Parameters': [],
|
||||
'Returns': [],
|
||||
'Raises': [],
|
||||
'Warns': [],
|
||||
'Other Parameters': [],
|
||||
'Attributes': [],
|
||||
'Methods': [],
|
||||
'See Also': [],
|
||||
'Notes': [],
|
||||
'Warnings': [],
|
||||
'References': '',
|
||||
'Examples': '',
|
||||
'index': {}
|
||||
}
|
||||
|
||||
self._parse()
|
||||
|
||||
def __getitem__(self,key):
|
||||
return self._parsed_data[key]
|
||||
|
||||
def __setitem__(self,key,val):
|
||||
if not self._parsed_data.has_key(key):
|
||||
warn("Unknown section %s" % key)
|
||||
else:
|
||||
self._parsed_data[key] = val
|
||||
|
||||
def _is_at_section(self):
|
||||
self._doc.seek_next_non_empty_line()
|
||||
|
||||
if self._doc.eof():
|
||||
return False
|
||||
|
||||
l1 = self._doc.peek().strip() # e.g. Parameters
|
||||
|
||||
if l1.startswith('.. index::'):
|
||||
return True
|
||||
|
||||
l2 = self._doc.peek(1).strip() # ---------- or ==========
|
||||
return l2.startswith('-'*len(l1)) or l2.startswith('='*len(l1))
|
||||
|
||||
def _strip(self,doc):
|
||||
i = 0
|
||||
j = 0
|
||||
for i,line in enumerate(doc):
|
||||
if line.strip(): break
|
||||
|
||||
for j,line in enumerate(doc[::-1]):
|
||||
if line.strip(): break
|
||||
|
||||
return doc[i:len(doc)-j]
|
||||
|
||||
def _read_to_next_section(self):
|
||||
section = self._doc.read_to_next_empty_line()
|
||||
|
||||
while not self._is_at_section() and not self._doc.eof():
|
||||
if not self._doc.peek(-1).strip(): # previous line was empty
|
||||
section += ['']
|
||||
|
||||
section += self._doc.read_to_next_empty_line()
|
||||
|
||||
return section
|
||||
|
||||
def _read_sections(self):
|
||||
while not self._doc.eof():
|
||||
data = self._read_to_next_section()
|
||||
name = data[0].strip()
|
||||
|
||||
if name.startswith('..'): # index section
|
||||
yield name, data[1:]
|
||||
elif len(data) < 2:
|
||||
yield StopIteration
|
||||
else:
|
||||
yield name, self._strip(data[2:])
|
||||
|
||||
def _parse_param_list(self,content):
|
||||
r = Reader(content)
|
||||
params = []
|
||||
while not r.eof():
|
||||
header = r.read().strip()
|
||||
if ' : ' in header:
|
||||
arg_name, arg_type = header.split(' : ')[:2]
|
||||
else:
|
||||
arg_name, arg_type = header, ''
|
||||
|
||||
desc = r.read_to_next_unindented_line()
|
||||
desc = dedent_lines(desc)
|
||||
|
||||
params.append((arg_name,arg_type,desc))
|
||||
|
||||
return params
|
||||
|
||||
|
||||
_name_rgx = re.compile(r"^\s*(:(?P<role>\w+):`(?P<name>[a-zA-Z0-9_.-]+)`|"
|
||||
r" (?P<name2>[a-zA-Z0-9_.-]+))\s*", re.X)
|
||||
def _parse_see_also(self, content):
|
||||
"""
|
||||
func_name : Descriptive text
|
||||
continued text
|
||||
another_func_name : Descriptive text
|
||||
func_name1, func_name2, :meth:`func_name`, func_name3
|
||||
|
||||
"""
|
||||
items = []
|
||||
|
||||
def parse_item_name(text):
|
||||
"""Match ':role:`name`' or 'name'"""
|
||||
m = self._name_rgx.match(text)
|
||||
if m:
|
||||
g = m.groups()
|
||||
if g[1] is None:
|
||||
return g[3], None
|
||||
else:
|
||||
return g[2], g[1]
|
||||
raise ValueError("%s is not a item name" % text)
|
||||
|
||||
def push_item(name, rest):
|
||||
if not name:
|
||||
return
|
||||
name, role = parse_item_name(name)
|
||||
items.append((name, list(rest), role))
|
||||
del rest[:]
|
||||
|
||||
current_func = None
|
||||
rest = []
|
||||
|
||||
for line in content:
|
||||
if not line.strip(): continue
|
||||
|
||||
m = self._name_rgx.match(line)
|
||||
if m and line[m.end():].strip().startswith(':'):
|
||||
push_item(current_func, rest)
|
||||
current_func, line = line[:m.end()], line[m.end():]
|
||||
rest = [line.split(':', 1)[1].strip()]
|
||||
if not rest[0]:
|
||||
rest = []
|
||||
elif not line.startswith(' '):
|
||||
push_item(current_func, rest)
|
||||
current_func = None
|
||||
if ',' in line:
|
||||
for func in line.split(','):
|
||||
push_item(func, [])
|
||||
elif line.strip():
|
||||
current_func = line
|
||||
elif current_func is not None:
|
||||
rest.append(line.strip())
|
||||
push_item(current_func, rest)
|
||||
return items
|
||||
|
||||
def _parse_index(self, section, content):
|
||||
"""
|
||||
.. index: default
|
||||
:refguide: something, else, and more
|
||||
|
||||
"""
|
||||
def strip_each_in(lst):
|
||||
return [s.strip() for s in lst]
|
||||
|
||||
out = {}
|
||||
section = section.split('::')
|
||||
if len(section) > 1:
|
||||
out['default'] = strip_each_in(section[1].split(','))[0]
|
||||
for line in content:
|
||||
line = line.split(':')
|
||||
if len(line) > 2:
|
||||
out[line[1]] = strip_each_in(line[2].split(','))
|
||||
return out
|
||||
|
||||
def _parse_summary(self):
|
||||
"""Grab signature (if given) and summary"""
|
||||
if self._is_at_section():
|
||||
return
|
||||
|
||||
summary = self._doc.read_to_next_empty_line()
|
||||
summary_str = " ".join([s.strip() for s in summary]).strip()
|
||||
if re.compile('^([\w., ]+=)?\s*[\w\.]+\(.*\)$').match(summary_str):
|
||||
self['Signature'] = summary_str
|
||||
if not self._is_at_section():
|
||||
self['Summary'] = self._doc.read_to_next_empty_line()
|
||||
else:
|
||||
self['Summary'] = summary
|
||||
|
||||
if not self._is_at_section():
|
||||
self['Extended Summary'] = self._read_to_next_section()
|
||||
|
||||
def _parse(self):
|
||||
self._doc.reset()
|
||||
self._parse_summary()
|
||||
|
||||
for (section,content) in self._read_sections():
|
||||
if not section.startswith('..'):
|
||||
section = ' '.join([s.capitalize() for s in section.split(' ')])
|
||||
if section in ('Parameters', 'Attributes', 'Methods',
|
||||
'Returns', 'Raises', 'Warns'):
|
||||
self[section] = self._parse_param_list(content)
|
||||
elif section.startswith('.. index::'):
|
||||
self['index'] = self._parse_index(section, content)
|
||||
elif section == 'See Also':
|
||||
self['See Also'] = self._parse_see_also(content)
|
||||
else:
|
||||
self[section] = content
|
||||
|
||||
# string conversion routines
|
||||
|
||||
def _str_header(self, name, symbol='-'):
|
||||
return [name, len(name)*symbol]
|
||||
|
||||
def _str_indent(self, doc, indent=4):
|
||||
out = []
|
||||
for line in doc:
|
||||
out += [' '*indent + line]
|
||||
return out
|
||||
|
||||
def _str_signature(self):
|
||||
if self['Signature']:
|
||||
return [self['Signature'].replace('*','\*')] + ['']
|
||||
else:
|
||||
return ['']
|
||||
|
||||
def _str_summary(self):
|
||||
if self['Summary']:
|
||||
return self['Summary'] + ['']
|
||||
else:
|
||||
return []
|
||||
|
||||
def _str_extended_summary(self):
|
||||
if self['Extended Summary']:
|
||||
return self['Extended Summary'] + ['']
|
||||
else:
|
||||
return []
|
||||
|
||||
def _str_param_list(self, name):
|
||||
out = []
|
||||
if self[name]:
|
||||
out += self._str_header(name)
|
||||
for param,param_type,desc in self[name]:
|
||||
out += ['%s : %s' % (param, param_type)]
|
||||
out += self._str_indent(desc)
|
||||
out += ['']
|
||||
return out
|
||||
|
||||
def _str_section(self, name):
|
||||
out = []
|
||||
if self[name]:
|
||||
out += self._str_header(name)
|
||||
out += self[name]
|
||||
out += ['']
|
||||
return out
|
||||
|
||||
def _str_see_also(self, func_role):
|
||||
if not self['See Also']: return []
|
||||
out = []
|
||||
out += self._str_header("See Also")
|
||||
last_had_desc = True
|
||||
for func, desc, role in self['See Also']:
|
||||
if role:
|
||||
link = ':%s:`%s`' % (role, func)
|
||||
elif func_role:
|
||||
link = ':%s:`%s`' % (func_role, func)
|
||||
else:
|
||||
link = "`%s`_" % func
|
||||
if desc or last_had_desc:
|
||||
out += ['']
|
||||
out += [link]
|
||||
else:
|
||||
out[-1] += ", %s" % link
|
||||
if desc:
|
||||
out += self._str_indent([' '.join(desc)])
|
||||
last_had_desc = True
|
||||
else:
|
||||
last_had_desc = False
|
||||
out += ['']
|
||||
return out
|
||||
|
||||
def _str_index(self):
|
||||
idx = self['index']
|
||||
out = []
|
||||
out += ['.. index:: %s' % idx.get('default','')]
|
||||
for section, references in idx.iteritems():
|
||||
if section == 'default':
|
||||
continue
|
||||
out += [' :%s: %s' % (section, ', '.join(references))]
|
||||
return out
|
||||
|
||||
def __str__(self, func_role=''):
|
||||
out = []
|
||||
out += self._str_signature()
|
||||
out += self._str_summary()
|
||||
out += self._str_extended_summary()
|
||||
for param_list in ('Parameters','Returns','Raises'):
|
||||
out += self._str_param_list(param_list)
|
||||
out += self._str_section('Warnings')
|
||||
out += self._str_see_also(func_role)
|
||||
for s in ('Notes','References','Examples'):
|
||||
out += self._str_section(s)
|
||||
for param_list in ('Attributes', 'Methods'):
|
||||
out += self._str_param_list(param_list)
|
||||
out += self._str_index()
|
||||
return '\n'.join(out)
|
||||
|
||||
|
||||
def indent(str,indent=4):
|
||||
indent_str = ' '*indent
|
||||
if str is None:
|
||||
return indent_str
|
||||
lines = str.split('\n')
|
||||
return '\n'.join(indent_str + l for l in lines)
|
||||
|
||||
def dedent_lines(lines):
|
||||
"""Deindent a list of lines maximally"""
|
||||
return textwrap.dedent("\n".join(lines)).split("\n")
|
||||
|
||||
def header(text, style='-'):
|
||||
return text + '\n' + style*len(text) + '\n'
|
||||
|
||||
|
||||
class FunctionDoc(NumpyDocString):
|
||||
def __init__(self, func, role='func', doc=None):
|
||||
self._f = func
|
||||
self._role = role # e.g. "func" or "meth"
|
||||
if doc is None:
|
||||
doc = inspect.getdoc(func) or ''
|
||||
try:
|
||||
NumpyDocString.__init__(self, doc)
|
||||
except ValueError, e:
|
||||
print '*'*78
|
||||
print "ERROR: '%s' while parsing `%s`" % (e, self._f)
|
||||
print '*'*78
|
||||
#print "Docstring follows:"
|
||||
#print doclines
|
||||
#print '='*78
|
||||
|
||||
if not self['Signature']:
|
||||
func, func_name = self.get_func()
|
||||
try:
|
||||
# try to read signature
|
||||
argspec = inspect.getargspec(func)
|
||||
argspec = inspect.formatargspec(*argspec)
|
||||
argspec = argspec.replace('*','\*')
|
||||
signature = '%s%s' % (func_name, argspec)
|
||||
except TypeError, e:
|
||||
signature = '%s()' % func_name
|
||||
self['Signature'] = signature
|
||||
|
||||
def get_func(self):
|
||||
func_name = getattr(self._f, '__name__', self.__class__.__name__)
|
||||
if inspect.isclass(self._f):
|
||||
func = getattr(self._f, '__call__', self._f.__init__)
|
||||
else:
|
||||
func = self._f
|
||||
return func, func_name
|
||||
|
||||
def __str__(self):
|
||||
out = ''
|
||||
|
||||
func, func_name = self.get_func()
|
||||
signature = self['Signature'].replace('*', '\*')
|
||||
|
||||
roles = {'func': 'function',
|
||||
'meth': 'method'}
|
||||
|
||||
if self._role:
|
||||
if not roles.has_key(self._role):
|
||||
print "Warning: invalid role %s" % self._role
|
||||
out += '.. %s:: %s\n \n\n' % (roles.get(self._role,''),
|
||||
func_name)
|
||||
|
||||
out += super(FunctionDoc, self).__str__(func_role=self._role)
|
||||
return out
|
||||
|
||||
|
||||
class ClassDoc(NumpyDocString):
|
||||
def __init__(self,cls,modulename='',func_doc=FunctionDoc,doc=None):
|
||||
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
|
||||
|
||||
if doc is None:
|
||||
doc = pydoc.getdoc(cls)
|
||||
|
||||
NumpyDocString.__init__(self, doc)
|
||||
|
||||
if not self['Methods']:
|
||||
self['Methods'] = [(name, '', '') for name in sorted(self.methods)]
|
||||
|
||||
if not self['Attributes']:
|
||||
self['Attributes'] = [(name, '', '')
|
||||
for name in sorted(self.properties)]
|
||||
|
||||
@property
|
||||
def methods(self):
|
||||
return [name for name,func in inspect.getmembers(self._cls)
|
||||
if not name.startswith('_') and callable(func)]
|
||||
|
||||
@property
|
||||
def properties(self):
|
||||
return [name for name,func in inspect.getmembers(self._cls)
|
||||
if not name.startswith('_') and func is None]
|
||||
@@ -0,0 +1,219 @@
|
||||
import re, inspect, textwrap, pydoc
|
||||
import sphinx
|
||||
from docscrape import NumpyDocString, FunctionDoc, ClassDoc
|
||||
|
||||
class SphinxDocString(NumpyDocString):
|
||||
use_plots = False
|
||||
|
||||
# string conversion routines
|
||||
def _str_header(self, name, symbol='`'):
|
||||
return ['.. rubric:: ' + name, '']
|
||||
|
||||
def _str_field_list(self, name):
|
||||
return [':' + name + ':']
|
||||
|
||||
def _str_indent(self, doc, indent=4):
|
||||
out = []
|
||||
for line in doc:
|
||||
out += [' '*indent + line]
|
||||
return out
|
||||
|
||||
def _str_signature(self):
|
||||
return ['']
|
||||
if self['Signature']:
|
||||
return ['``%s``' % self['Signature']] + ['']
|
||||
else:
|
||||
return ['']
|
||||
|
||||
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(['**%s** : %s' % (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, name):
|
||||
"""
|
||||
Generate a member listing, autosummary:: table where possible,
|
||||
and a table where not.
|
||||
|
||||
"""
|
||||
out = []
|
||||
if self[name]:
|
||||
out += ['.. rubric:: %s' % name, '']
|
||||
prefix = getattr(self, '_name', '')
|
||||
|
||||
if prefix:
|
||||
prefix = '~%s.' % prefix
|
||||
|
||||
autosum = []
|
||||
others = []
|
||||
for param, param_type, desc in self[name]:
|
||||
param = param.strip()
|
||||
if not self._obj or hasattr(self._obj, param):
|
||||
autosum += [" %s%s" % (prefix, param)]
|
||||
else:
|
||||
others.append((param, param_type, desc))
|
||||
|
||||
if autosum:
|
||||
out += ['.. autosummary::', ' :toctree:', '']
|
||||
out += autosum
|
||||
|
||||
if others:
|
||||
maxlen_0 = max([len(x[0]) for x in others])
|
||||
maxlen_1 = max([len(x[1]) for x in others])
|
||||
hdr = "="*maxlen_0 + " " + "="*maxlen_1 + " " + "="*10
|
||||
fmt = '%%%ds %%%ds ' % (maxlen_0, maxlen_1)
|
||||
n_indent = maxlen_0 + maxlen_1 + 4
|
||||
out += [hdr]
|
||||
for param, param_type, desc in others:
|
||||
out += [fmt % (param.strip(), param_type)]
|
||||
out += self._str_indent(desc, n_indent)
|
||||
out += [hdr]
|
||||
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(SphinxDocString, self)._str_see_also(func_role)
|
||||
out = ['.. seealso::', '']
|
||||
out += self._str_indent(see_also[2:])
|
||||
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 += ['.. index:: %s' % idx.get('default','')]
|
||||
for section, references in idx.iteritems():
|
||||
if section == 'default':
|
||||
continue
|
||||
elif section == 'refguide':
|
||||
out += [' single: %s' % (', '.join(references))]
|
||||
else:
|
||||
out += [' %s: %s' % (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
|
||||
if sphinx.__version__ >= "0.6":
|
||||
out += ['.. only:: latex','']
|
||||
else:
|
||||
out += ['.. latexonly::','']
|
||||
items = []
|
||||
for line in self['References']:
|
||||
m = re.match(r'.. \[([a-z0-9._-]+)\]', line, re.I)
|
||||
if m:
|
||||
items.append(m.group(1))
|
||||
out += [' ' + ", ".join(["[%s]_" % item for item in items]), '']
|
||||
return out
|
||||
|
||||
def _str_examples(self):
|
||||
examples_str = "\n".join(self['Examples'])
|
||||
|
||||
if (self.use_plots and 'import matplotlib' in examples_str
|
||||
and 'plot::' not in examples_str):
|
||||
out = []
|
||||
out += self._str_header('Examples')
|
||||
out += ['.. plot::', '']
|
||||
out += self._str_indent(self['Examples'])
|
||||
out += ['']
|
||||
return out
|
||||
else:
|
||||
return self._str_section('Examples')
|
||||
|
||||
def __str__(self, indent=0, func_role="obj"):
|
||||
out = []
|
||||
out += self._str_signature()
|
||||
out += self._str_index() + ['']
|
||||
out += self._str_summary()
|
||||
out += self._str_extended_summary()
|
||||
for param_list in ('Parameters', 'Returns', 'Raises'):
|
||||
out += self._str_param_list(param_list)
|
||||
out += self._str_warnings()
|
||||
out += self._str_see_also(func_role)
|
||||
out += self._str_section('Notes')
|
||||
out += self._str_references()
|
||||
out += self._str_examples()
|
||||
for param_list in ('Attributes', 'Methods'):
|
||||
out += self._str_member_list(param_list)
|
||||
out = self._str_indent(out,indent)
|
||||
return '\n'.join(out)
|
||||
|
||||
class SphinxFunctionDoc(SphinxDocString, FunctionDoc):
|
||||
pass
|
||||
|
||||
class SphinxClassDoc(SphinxDocString, ClassDoc):
|
||||
pass
|
||||
|
||||
class SphinxObjDoc(SphinxDocString):
|
||||
def __init__(self, obj, doc):
|
||||
self._f = obj
|
||||
SphinxDocString.__init__(self, doc)
|
||||
|
||||
def get_doc_object(obj, what=None, doc=None):
|
||||
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)
|
||||
elif what in ('function', 'method'):
|
||||
return SphinxFunctionDoc(obj, '', doc=doc)
|
||||
else:
|
||||
if doc is None:
|
||||
doc = pydoc.getdoc(obj)
|
||||
return SphinxObjDoc(obj, doc)
|
||||
@@ -0,0 +1,192 @@
|
||||
"""
|
||||
========
|
||||
numpydoc
|
||||
========
|
||||
|
||||
Sphinx extension that handles docstrings in the Numpy standard format. [1]
|
||||
|
||||
It will:
|
||||
|
||||
- Convert Parameters etc. sections to field lists.
|
||||
- Convert See Also section to a See also entry.
|
||||
- Renumber references.
|
||||
- Extract the signature from the docstring, if it can't be determined otherwise.
|
||||
|
||||
.. [1] http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines#docstring-standard
|
||||
|
||||
"""
|
||||
|
||||
import os, re, pydoc
|
||||
from docscrape_sphinx import get_doc_object, SphinxDocString
|
||||
from sphinx.util.compat import Directive
|
||||
import inspect
|
||||
|
||||
def mangle_docstrings(app, what, name, obj, options, lines,
|
||||
reference_offset=[0]):
|
||||
|
||||
if what == 'module':
|
||||
# Strip top title
|
||||
title_re = re.compile(ur'^\s*[#*=]{4,}\n[a-z0-9 -]+\n[#*=]{4,}\s*',
|
||||
re.I|re.S)
|
||||
lines[:] = title_re.sub(u'', u"\n".join(lines)).split(u"\n")
|
||||
else:
|
||||
doc = get_doc_object(obj, what, u"\n".join(lines))
|
||||
doc.use_plots = app.config.numpydoc_use_plots
|
||||
lines[:] = unicode(doc).split(u"\n")
|
||||
|
||||
if app.config.numpydoc_edit_link and hasattr(obj, '__name__') and \
|
||||
obj.__name__:
|
||||
if hasattr(obj, '__module__'):
|
||||
v = dict(full_name=u"%s.%s" % (obj.__module__, obj.__name__))
|
||||
else:
|
||||
v = dict(full_name=obj.__name__)
|
||||
lines += [u'', u'.. htmlonly::', '']
|
||||
lines += [u' %s' % x for x in
|
||||
(app.config.numpydoc_edit_link % v).split("\n")]
|
||||
|
||||
# replace reference numbers so that there are no duplicates
|
||||
references = []
|
||||
for line in lines:
|
||||
line = line.strip()
|
||||
m = re.match(ur'^.. \[([a-z0-9_.-])\]', line, re.I)
|
||||
if m:
|
||||
references.append(m.group(1))
|
||||
|
||||
# start renaming from the longest string, to avoid overwriting parts
|
||||
references.sort(key=lambda x: -len(x))
|
||||
if references:
|
||||
for i, line in enumerate(lines):
|
||||
for r in references:
|
||||
if re.match(ur'^\d+$', r):
|
||||
new_r = u"R%d" % (reference_offset[0] + int(r))
|
||||
else:
|
||||
new_r = u"%s%d" % (r, reference_offset[0])
|
||||
lines[i] = lines[i].replace(u'[%s]_' % r,
|
||||
u'[%s]_' % new_r)
|
||||
lines[i] = lines[i].replace(u'.. [%s]' % r,
|
||||
u'.. [%s]' % new_r)
|
||||
|
||||
reference_offset[0] += len(references)
|
||||
|
||||
def mangle_signature(app, what, name, obj, options, sig, retann):
|
||||
# Do not try to inspect classes that don't define `__init__`
|
||||
if (inspect.isclass(obj) and
|
||||
'initializes x; see ' in pydoc.getdoc(obj.__init__)):
|
||||
return '', ''
|
||||
|
||||
if not (callable(obj) or hasattr(obj, '__argspec_is_invalid_')): return
|
||||
if not hasattr(obj, '__doc__'): return
|
||||
|
||||
doc = SphinxDocString(pydoc.getdoc(obj))
|
||||
if doc['Signature']:
|
||||
sig = re.sub(u"^[^(]*", u"", doc['Signature'])
|
||||
return sig, u''
|
||||
|
||||
def initialize(app):
|
||||
try:
|
||||
app.connect('autodoc-process-signature', mangle_signature)
|
||||
except:
|
||||
monkeypatch_sphinx_ext_autodoc()
|
||||
|
||||
def setup(app, get_doc_object_=get_doc_object):
|
||||
global get_doc_object
|
||||
get_doc_object = get_doc_object_
|
||||
|
||||
app.connect('autodoc-process-docstring', mangle_docstrings)
|
||||
app.connect('builder-inited', initialize)
|
||||
app.add_config_value('numpydoc_edit_link', None, True)
|
||||
app.add_config_value('numpydoc_use_plots', None, False)
|
||||
|
||||
# Extra mangling directives
|
||||
name_type = {
|
||||
'cfunction': 'function',
|
||||
'cmember': 'attribute',
|
||||
'cmacro': 'function',
|
||||
'ctype': 'class',
|
||||
'cvar': 'object',
|
||||
'class': 'class',
|
||||
'function': 'function',
|
||||
'attribute': 'attribute',
|
||||
'method': 'function',
|
||||
'staticmethod': 'function',
|
||||
'classmethod': 'function',
|
||||
}
|
||||
|
||||
for name, objtype in name_type.items():
|
||||
app.add_directive('np-' + name, wrap_mangling_directive(name, objtype))
|
||||
|
||||
#------------------------------------------------------------------------------
|
||||
# Input-mangling directives
|
||||
#------------------------------------------------------------------------------
|
||||
from docutils.statemachine import ViewList
|
||||
|
||||
def get_directive(name):
|
||||
from docutils.parsers.rst import directives
|
||||
try:
|
||||
return directives.directive(name, None, None)[0]
|
||||
except AttributeError:
|
||||
pass
|
||||
try:
|
||||
# docutils 0.4
|
||||
return directives._directives[name]
|
||||
except (AttributeError, KeyError):
|
||||
raise RuntimeError("No directive named '%s' found" % name)
|
||||
|
||||
def wrap_mangling_directive(base_directive_name, objtype):
|
||||
base_directive = get_directive(base_directive_name)
|
||||
|
||||
if inspect.isfunction(base_directive):
|
||||
base_func = base_directive
|
||||
class base_directive(Directive):
|
||||
required_arguments = base_func.arguments[0]
|
||||
optional_arguments = base_func.arguments[1]
|
||||
final_argument_whitespace = base_func.arguments[2]
|
||||
option_spec = base_func.options
|
||||
has_content = base_func.content
|
||||
def run(self):
|
||||
return base_func(self.name, self.arguments, self.options,
|
||||
self.content, self.lineno,
|
||||
self.content_offset, self.block_text,
|
||||
self.state, self.state_machine)
|
||||
|
||||
class directive(base_directive):
|
||||
def run(self):
|
||||
env = self.state.document.settings.env
|
||||
|
||||
name = None
|
||||
if self.arguments:
|
||||
m = re.match(r'^(.*\s+)?(.*?)(\(.*)?', self.arguments[0])
|
||||
name = m.group(2).strip()
|
||||
|
||||
if not name:
|
||||
name = self.arguments[0]
|
||||
|
||||
lines = list(self.content)
|
||||
mangle_docstrings(env.app, objtype, name, None, None, lines)
|
||||
self.content = ViewList(lines, self.content.parent)
|
||||
|
||||
return base_directive.run(self)
|
||||
|
||||
return directive
|
||||
|
||||
#------------------------------------------------------------------------------
|
||||
# Monkeypatch sphinx.ext.autodoc to accept argspecless autodocs (Sphinx < 0.5)
|
||||
#------------------------------------------------------------------------------
|
||||
|
||||
def monkeypatch_sphinx_ext_autodoc():
|
||||
global _original_format_signature
|
||||
import sphinx.ext.autodoc
|
||||
|
||||
if sphinx.ext.autodoc.format_signature is our_format_signature:
|
||||
return
|
||||
|
||||
print "[numpydoc] Monkeypatching sphinx.ext.autodoc ..."
|
||||
_original_format_signature = sphinx.ext.autodoc.format_signature
|
||||
sphinx.ext.autodoc.format_signature = our_format_signature
|
||||
|
||||
def our_format_signature(what, obj):
|
||||
r = mangle_signature(None, what, None, obj, None, None, None)
|
||||
if r is not None:
|
||||
return r[0]
|
||||
else:
|
||||
return _original_format_signature(what, obj)
|
||||
Reference in New Issue
Block a user