diff --git a/doc/sphinxext/LICENSE.txt b/doc/sphinxext/LICENSE.txt
index 079cedc4d604461bd531edbff680681d62096399..aec412b2064face3e6dbe7ded8ba034b9a3ac146 100644
--- a/doc/sphinxext/LICENSE.txt
+++ b/doc/sphinxext/LICENSE.txt
@@ -27,12 +27,10 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-------------------------------------------------------------------------------
The files
- - numpydoc.py
- - autosummary.py
- - autosummary_generate.py
- - docscrape.py
- - docscrape_sphinx.py
- - phantom_import.py
+ - numpydoc/numpydoc.py
+ - numpydoc/docscrape.py
+ - numpydoc/docscrape_sphinx.py
+ - numpydoc/phantom_import.py
have the following license:
Copyright (C) 2008 Stefan van der Walt <stefan@mentat.za.net>, Pauli Virtanen <pav@iki.fi>
@@ -62,9 +60,9 @@ POSSIBILITY OF SUCH DAMAGE.
-------------------------------------------------------------------------------
The files
- - compiler_unparse.py
- - comment_eater.py
- - traitsdoc.py
+ - numpydoc/compiler_unparse.py
+ - numpydoc/comment_eater.py
+ - numpydoc/traitsdoc.py
have the following license:
This software is OSI Certified Open Source Software.
@@ -98,10 +96,9 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-------------------------------------------------------------------------------
- The files
- - only_directives.py
- - plot_directive.py
- originate from Matplotlib (http://matplotlib.sf.net/) which has
+ The file
+ - numpydoc/plot_directive.py
+ originates from Matplotlib (http://matplotlib.sf.net/) which has
the following license:
Copyright (c) 2002-2008 John D. Hunter; All Rights Reserved.
diff --git a/doc/sphinxext/__init__.py b/doc/sphinxext/__init__.py
deleted file mode 100644
index ae9073bc4115fd5fb7ef03381da59f4d9115bca2..0000000000000000000000000000000000000000
--- a/doc/sphinxext/__init__.py
+++ /dev/null
@@ -1 +0,0 @@
-from numpydoc import setup
diff --git a/doc/sphinxext/numpydoc/__init__.py b/doc/sphinxext/numpydoc/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..0fce2cf747e2331002841a5cf4c4c8c9d1568ab6
--- /dev/null
+++ b/doc/sphinxext/numpydoc/__init__.py
@@ -0,0 +1,3 @@
+from __future__ import division, absolute_import, print_function
+
+from .numpydoc import setup
diff --git a/doc/sphinxext/comment_eater.py b/doc/sphinxext/numpydoc/comment_eater.py
similarity index 93%
rename from doc/sphinxext/comment_eater.py
rename to doc/sphinxext/numpydoc/comment_eater.py
index e11eea90210734962afe50e53ee5892be6eb100e..8cddd3305f0bc17480b1269801f1d43af274c924 100644
--- a/doc/sphinxext/comment_eater.py
+++ b/doc/sphinxext/numpydoc/comment_eater.py
@@ -1,10 +1,17 @@
-from cStringIO import StringIO
+from __future__ import division, absolute_import, print_function
+
+import sys
+if sys.version_info[0] >= 3:
+ from io import StringIO
+else:
+ from io import StringIO
+
import compiler
import inspect
import textwrap
import tokenize
-from compiler_unparse import unparse
+from .compiler_unparse import unparse
class Comment(object):
@@ -68,7 +75,11 @@ class CommentBlocker(object):
def process_file(self, file):
""" Process a file object.
"""
- for token in tokenize.generate_tokens(file.next):
+ if sys.version_info[0] >= 3:
+ nxt = file.__next__
+ else:
+ nxt = file.next
+ for token in tokenize.generate_tokens(nxt):
self.process_token(*token)
self.make_index()
@@ -95,7 +106,7 @@ class CommentBlocker(object):
def new_comment(self, string, start, end, line):
""" Possibly add a new comment.
-
+
Only adds a new comment if this comment is the only thing on the line.
Otherwise, it extends the noncomment block.
"""
diff --git a/doc/sphinxext/compiler_unparse.py b/doc/sphinxext/numpydoc/compiler_unparse.py
similarity index 99%
rename from doc/sphinxext/compiler_unparse.py
rename to doc/sphinxext/numpydoc/compiler_unparse.py
index ffcf51b353a106e50b3c4ec5bbd4ab4342bc7528..8933a83db3f23cdb1955fb7bb0a70abb5c3f8a0f 100644
--- a/doc/sphinxext/compiler_unparse.py
+++ b/doc/sphinxext/numpydoc/compiler_unparse.py
@@ -10,13 +10,18 @@
fixme: We may want to move to using _ast trees because the compiler for
them is about 6 times faster than compiler.compile.
"""
+from __future__ import division, absolute_import, print_function
import sys
-import cStringIO
from compiler.ast import Const, Name, Tuple, Div, Mul, Sub, Add
+if sys.version_info[0] >= 3:
+ from io import StringIO
+else:
+ from StringIO import StringIO
+
def unparse(ast, single_line_functions=False):
- s = cStringIO.StringIO()
+ s = StringIO()
UnparseCompilerAst(ast, s, single_line_functions)
return s.getvalue().lstrip()
@@ -101,13 +106,13 @@ class UnparseCompilerAst:
if i != len(t.nodes)-1:
self._write(") and (")
self._write(")")
-
+
def _AssAttr(self, t):
""" Handle assigning an attribute of an object
"""
self._dispatch(t.expr)
self._write('.'+t.attrname)
-
+
def _Assign(self, t):
""" Expression Assignment such as "a = 1".
@@ -145,36 +150,36 @@ class UnparseCompilerAst:
def _AugAssign(self, t):
""" +=,-=,*=,/=,**=, etc. operations
"""
-
+
self._fill()
self._dispatch(t.node)
self._write(' '+t.op+' ')
self._dispatch(t.expr)
if not self._do_indent:
self._write(';')
-
+
def _Bitand(self, t):
""" Bit and operation.
"""
-
+
for i, node in enumerate(t.nodes):
self._write("(")
self._dispatch(node)
self._write(")")
if i != len(t.nodes)-1:
self._write(" & ")
-
+
def _Bitor(self, t):
""" Bit or operation
"""
-
+
for i, node in enumerate(t.nodes):
self._write("(")
self._dispatch(node)
self._write(")")
if i != len(t.nodes)-1:
self._write(" | ")
-
+
def _CallFunc(self, t):
""" Function call.
"""
@@ -249,7 +254,7 @@ class UnparseCompilerAst:
self._write(name)
if asname is not None:
self._write(" as "+asname)
-
+
def _Function(self, t):
""" Handle function definitions
"""
diff --git a/doc/sphinxext/docscrape.py b/doc/sphinxext/numpydoc/docscrape.py
similarity index 88%
rename from doc/sphinxext/docscrape.py
rename to doc/sphinxext/numpydoc/docscrape.py
index 1e3ae28b2e0e8659e3cb5775a72c86f04520d5a8..4ee0f2e400d0ef83c1e8a863770786842350ae3e 100644
--- a/doc/sphinxext/docscrape.py
+++ b/doc/sphinxext/numpydoc/docscrape.py
@@ -1,13 +1,15 @@
"""Extract reference documentation from the NumPy source tree.
"""
+from __future__ import division, absolute_import, print_function
import inspect
import textwrap
import re
import pydoc
-from StringIO import StringIO
from warnings import warn
+import collections
+
class Reader(object):
"""A line-based string reader.
@@ -98,7 +100,6 @@ class NumpyDocString(object):
'Warns': [],
'Other Parameters': [],
'Attributes': [],
- 'Instance Variables': [],
'Methods': [],
'See Also': [],
'Notes': [],
@@ -114,7 +115,7 @@ class NumpyDocString(object):
return self._parsed_data[key]
def __setitem__(self,key,val):
- if not self._parsed_data.has_key(key):
+ if key not in self._parsed_data:
warn("Unknown section %s" % key)
else:
self._parsed_data[key] = val
@@ -266,13 +267,17 @@ class NumpyDocString(object):
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:
+ # If several signatures present, take the last one
+ while True:
+ 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():
+ continue
+ break
+
+ if summary is not None:
self['Summary'] = summary
if not self._is_at_section():
@@ -286,8 +291,7 @@ class NumpyDocString(object):
if not section.startswith('..'):
section = ' '.join([s.capitalize() for s in section.split(' ')])
if section in ('Parameters', 'Returns', 'Raises', 'Warns',
- 'Other Parameters', 'Attributes',
- 'Instance Variables', 'Methods'):
+ 'Other Parameters', 'Attributes', 'Methods'):
self[section] = self._parse_param_list(content)
elif section.startswith('.. index::'):
self['index'] = self._parse_index(section, content)
@@ -330,7 +334,10 @@ class NumpyDocString(object):
if self[name]:
out += self._str_header(name)
for param,param_type,desc in self[name]:
- out += ['%s : %s' % (param, param_type)]
+ if param_type:
+ out += ['%s : %s' % (param, param_type)]
+ else:
+ out += [param]
out += self._str_indent(desc)
out += ['']
return out
@@ -372,7 +379,7 @@ class NumpyDocString(object):
idx = self['index']
out = []
out += ['.. index:: %s' % idx.get('default','')]
- for section, references in idx.iteritems():
+ for section, references in idx.items():
if section == 'default':
continue
out += [' :%s: %s' % (section, ', '.join(references))]
@@ -390,7 +397,7 @@ class NumpyDocString(object):
out += self._str_see_also(func_role)
for s in ('Notes','References','Examples'):
out += self._str_section(s)
- for param_list in ('Instance Variables', 'Attributes', 'Methods'):
+ for param_list in ('Attributes', 'Methods'):
out += self._str_param_list(param_list)
out += self._str_index()
return '\n'.join(out)
@@ -430,7 +437,7 @@ class FunctionDoc(NumpyDocString):
argspec = inspect.formatargspec(*argspec)
argspec = argspec.replace('*','\*')
signature = '%s%s' % (func_name, argspec)
- except TypeError, e:
+ except TypeError as e:
signature = '%s()' % func_name
self['Signature'] = signature
@@ -452,8 +459,8 @@ class FunctionDoc(NumpyDocString):
'meth': 'method'}
if self._role:
- if not roles.has_key(self._role):
- print "Warning: invalid role %s" % self._role
+ if self._role not in roles:
+ print("Warning: invalid role %s" % self._role)
out += '.. %s:: %s\n \n\n' % (roles.get(self._role,''),
func_name)
@@ -483,12 +490,19 @@ class ClassDoc(NumpyDocString):
NumpyDocString.__init__(self, doc)
if config.get('show_class_members', True):
- 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)]
+ def splitlines_x(s):
+ if not s:
+ return []
+ else:
+ return s.splitlines()
+
+ for field, items in [('Methods', self.methods),
+ ('Attributes', self.properties)]:
+ if not self[field]:
+ self[field] = [
+ (name, '',
+ splitlines_x(pydoc.getdoc(getattr(self._cls, name))))
+ for name in sorted(items)]
@property
def methods(self):
@@ -497,11 +511,13 @@ class ClassDoc(NumpyDocString):
return [name for name,func in inspect.getmembers(self._cls)
if ((not name.startswith('_')
or name in self.extra_public_methods)
- and callable(func))]
+ and isinstance(func, collections.Callable))]
@property
def properties(self):
if self._cls is None:
return []
return [name for name,func in inspect.getmembers(self._cls)
- if not name.startswith('_') and func is None]
+ if not name.startswith('_') and
+ (func is None or isinstance(func, property) or
+ inspect.isgetsetdescriptor(func))]
diff --git a/doc/sphinxext/docscrape_sphinx.py b/doc/sphinxext/numpydoc/docscrape_sphinx.py
similarity index 72%
rename from doc/sphinxext/docscrape_sphinx.py
rename to doc/sphinxext/numpydoc/docscrape_sphinx.py
index 28465a22ca675ab2aebb3541e64fc6e49c7c492e..1ebce8ccbe75aef1985cba37b810c7f4cc855290 100644
--- a/doc/sphinxext/docscrape_sphinx.py
+++ b/doc/sphinxext/numpydoc/docscrape_sphinx.py
@@ -1,6 +1,15 @@
-import re, inspect, textwrap, pydoc
+from __future__ import division, absolute_import, print_function
+
+import sys, re, inspect, textwrap, pydoc
import sphinx
-from docscrape import NumpyDocString, FunctionDoc, ClassDoc
+import collections
+from .docscrape import NumpyDocString, FunctionDoc, ClassDoc
+
+if sys.version_info[0] >= 3:
+ sixu = lambda s: s
+else:
+ sixu = lambda s: unicode(s, 'unicode_escape')
+
class SphinxDocString(NumpyDocString):
def __init__(self, docstring, config={}):
@@ -33,16 +42,37 @@ class SphinxDocString(NumpyDocString):
def _str_extended_summary(self):
return self['Extended Summary'] + ['']
+ def _str_returns(self):
+ out = []
+ if self['Returns']:
+ out += self._str_field_list('Returns')
+ out += ['']
+ for param, param_type, desc in self['Returns']:
+ if param_type:
+ out += self._str_indent(['**%s** : %s' % (param.strip(),
+ param_type)])
+ else:
+ out += self._str_indent([param.strip()])
+ if desc:
+ out += ['']
+ out += self._str_indent(desc, 8)
+ out += ['']
+ return out
+
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)
+ for param, param_type, desc in self[name]:
+ if param_type:
+ out += self._str_indent(['**%s** : %s' % (param.strip(),
+ param_type)])
+ else:
+ out += self._str_indent(['**%s**' % param.strip()])
+ if desc:
+ out += ['']
+ out += self._str_indent(desc, 8)
out += ['']
return out
@@ -72,7 +102,16 @@ class SphinxDocString(NumpyDocString):
others = []
for param, param_type, desc in self[name]:
param = param.strip()
- if not self._obj or hasattr(self._obj, param):
+
+ # Check if the referenced member can have a docstring or not
+ param_obj = getattr(self._obj, param, None)
+ if not (callable(param_obj)
+ or isinstance(param_obj, property)
+ or inspect.isgetsetdescriptor(param_obj)):
+ param_obj = None
+
+ if param_obj and (pydoc.getdoc(param_obj) or not desc):
+ # Referenced object has a docstring
autosum += [" %s%s" % (prefix, param)]
else:
others.append((param, param_type, desc))
@@ -82,15 +121,15 @@ class SphinxDocString(NumpyDocString):
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]
+ maxlen_0 = max(3, max([len(x[0]) for x in others]))
+ hdr = sixu("=")*maxlen_0 + sixu(" ") + sixu("=")*10
+ fmt = sixu('%%%ds %%s ') % (maxlen_0,)
+ out += ['', hdr]
for param, param_type, desc in others:
- out += [fmt % (param.strip(), param_type)]
- out += self._str_indent(desc, n_indent)
+ desc = sixu(" ").join(x.strip() for x in desc).strip()
+ if param_type:
+ desc = "(%s) %s" % (param_type, desc)
+ out += [fmt % (param.strip(), desc)]
out += [hdr]
out += ['']
return out
@@ -127,7 +166,7 @@ class SphinxDocString(NumpyDocString):
return out
out += ['.. index:: %s' % idx.get('default','')]
- for section, references in idx.iteritems():
+ for section, references in idx.items():
if section == 'default':
continue
elif section == 'refguide':
@@ -178,15 +217,16 @@ class SphinxDocString(NumpyDocString):
out += self._str_index() + ['']
out += self._str_summary()
out += self._str_extended_summary()
- for param_list in ('Parameters', 'Returns', 'Other Parameters',
- 'Raises', 'Warns'):
+ out += self._str_param_list('Parameters')
+ out += self._str_returns()
+ for param_list in ('Other Parameters', 'Raises', 'Warns'):
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 ('Instance Variables', 'Attributes', 'Methods'):
+ for param_list in ('Attributes', 'Methods'):
out += self._str_member_list(param_list)
out = self._str_indent(out,indent)
return '\n'.join(out)
@@ -212,7 +252,7 @@ def get_doc_object(obj, what=None, doc=None, config={}):
what = 'class'
elif inspect.ismodule(obj):
what = 'module'
- elif callable(obj):
+ elif isinstance(obj, collections.Callable):
what = 'function'
else:
what = 'object'
diff --git a/doc/sphinxext/numpydoc/linkcode.py b/doc/sphinxext/numpydoc/linkcode.py
new file mode 100644
index 0000000000000000000000000000000000000000..1ad3ab82cb49c8097c9bcafa025930084c4bf7b5
--- /dev/null
+++ b/doc/sphinxext/numpydoc/linkcode.py
@@ -0,0 +1,83 @@
+# -*- coding: utf-8 -*-
+"""
+ linkcode
+ ~~~~~~~~
+
+ Add external links to module code in Python object descriptions.
+
+ :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+ :license: BSD, see LICENSE for details.
+
+"""
+from __future__ import division, absolute_import, print_function
+
+import warnings
+import collections
+
+warnings.warn("This extension has been accepted to Sphinx upstream. "
+ "Use the version from there (Sphinx >= 1.2) "
+ "https://bitbucket.org/birkenfeld/sphinx/pull-request/47/sphinxextlinkcode",
+ FutureWarning, stacklevel=1)
+
+
+from docutils import nodes
+
+from sphinx import addnodes
+from sphinx.locale import _
+from sphinx.errors import SphinxError
+
+class LinkcodeError(SphinxError):
+ category = "linkcode error"
+
+def doctree_read(app, doctree):
+ env = app.builder.env
+
+ resolve_target = getattr(env.config, 'linkcode_resolve', None)
+ if not isinstance(env.config.linkcode_resolve, collections.Callable):
+ raise LinkcodeError(
+ "Function `linkcode_resolve` is not given in conf.py")
+
+ domain_keys = dict(
+ py=['module', 'fullname'],
+ c=['names'],
+ cpp=['names'],
+ js=['object', 'fullname'],
+ )
+
+ for objnode in doctree.traverse(addnodes.desc):
+ domain = objnode.get('domain')
+ uris = set()
+ for signode in objnode:
+ if not isinstance(signode, addnodes.desc_signature):
+ continue
+
+ # Convert signode to a specified format
+ info = {}
+ for key in domain_keys.get(domain, []):
+ value = signode.get(key)
+ if not value:
+ value = ''
+ info[key] = value
+ if not info:
+ continue
+
+ # Call user code to resolve the link
+ uri = resolve_target(domain, info)
+ if not uri:
+ # no source
+ continue
+
+ if uri in uris or not uri:
+ # only one link per name, please
+ continue
+ uris.add(uri)
+
+ onlynode = addnodes.only(expr='html')
+ onlynode += nodes.reference('', '', internal=False, refuri=uri)
+ onlynode[0] += nodes.inline('', _('[source]'),
+ classes=['viewcode-link'])
+ signode += onlynode
+
+def setup(app):
+ app.connect('doctree-read', doctree_read)
+ app.add_config_value('linkcode_resolve', None, '')
diff --git a/doc/sphinxext/numpydoc.py b/doc/sphinxext/numpydoc/numpydoc.py
similarity index 71%
rename from doc/sphinxext/numpydoc.py
rename to doc/sphinxext/numpydoc/numpydoc.py
index 7679352c2e235850ad9c28ef3943feb6c614af76..4f5f716c4c995ff75ae177714f59d97e849ad665 100644
--- a/doc/sphinxext/numpydoc.py
+++ b/doc/sphinxext/numpydoc/numpydoc.py
@@ -15,16 +15,24 @@ It will:
.. [1] https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
"""
+from __future__ import division, absolute_import, print_function
+import os, sys, re, pydoc
import sphinx
+import inspect
+import collections
if sphinx.__version__ < '1.0.1':
raise RuntimeError("Sphinx 1.0.1 or newer is required")
-import os, re, pydoc
-from docscrape_sphinx import get_doc_object, SphinxDocString
+from .docscrape_sphinx import get_doc_object, SphinxDocString
from sphinx.util.compat import Directive
-import inspect
+
+if sys.version_info[0] >= 3:
+ sixu = lambda s: s
+else:
+ sixu = lambda s: unicode(s, 'unicode_escape')
+
def mangle_docstrings(app, what, name, obj, options, lines,
reference_offset=[0]):
@@ -34,28 +42,32 @@ def mangle_docstrings(app, what, name, obj, options, lines,
if what == 'module':
# Strip top title
- title_re = re.compile(ur'^\s*[#*=]{4,}\n[a-z0-9 -]+\n[#*=]{4,}\s*',
+ title_re = re.compile(sixu('^\\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")
+ lines[:] = title_re.sub(sixu(''), sixu("\n").join(lines)).split(sixu("\n"))
else:
- doc = get_doc_object(obj, what, u"\n".join(lines), config=cfg)
- lines[:] = unicode(doc).split(u"\n")
+ doc = get_doc_object(obj, what, sixu("\n").join(lines), config=cfg)
+ if sys.version_info[0] >= 3:
+ doc = str(doc)
+ else:
+ doc = str(doc).decode('utf-8')
+ lines[:] = doc.split(sixu("\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__))
+ v = dict(full_name=sixu("%s.%s") % (obj.__module__, obj.__name__))
else:
v = dict(full_name=obj.__name__)
- lines += [u'', u'.. htmlonly::', '']
- lines += [u' %s' % x for x in
+ lines += [sixu(''), sixu('.. htmlonly::'), sixu('')]
+ lines += [sixu(' %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)
+ m = re.match(sixu('^.. \\[([a-z0-9_.-])\\]'), line, re.I)
if m:
references.append(m.group(1))
@@ -64,14 +76,14 @@ def mangle_docstrings(app, what, name, obj, options, lines,
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))
+ if re.match(sixu('^\\d+$'), r):
+ new_r = sixu("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)
+ new_r = sixu("%s%d") % (r, reference_offset[0])
+ lines[i] = lines[i].replace(sixu('[%s]_') % r,
+ sixu('[%s]_') % new_r)
+ lines[i] = lines[i].replace(sixu('.. [%s]') % r,
+ sixu('.. [%s]') % new_r)
reference_offset[0] += len(references)
@@ -82,15 +94,18 @@ def mangle_signature(app, what, name, obj, options, sig, retann):
'initializes x; see ' in pydoc.getdoc(obj.__init__))):
return '', ''
- if not (callable(obj) or hasattr(obj, '__argspec_is_invalid_')): return
+ if not (isinstance(obj, collections.Callable) 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''
+ sig = re.sub(sixu("^[^(]*"), sixu(""), doc['Signature'])
+ return sig, sixu('')
def setup(app, get_doc_object_=get_doc_object):
+ if not hasattr(app, 'add_config_value'):
+ return # probably called by nose, better bail out
+
global get_doc_object
get_doc_object = get_doc_object_
@@ -120,7 +135,7 @@ class ManglingDomainBase(object):
self.wrap_mangling_directives()
def wrap_mangling_directives(self):
- for name, objtype in self.directive_mangling_map.items():
+ for name, objtype in list(self.directive_mangling_map.items()):
self.directives[name] = wrap_mangling_directive(
self.directives[name], objtype)
@@ -135,6 +150,7 @@ class NumpyPythonDomain(ManglingDomainBase, PythonDomain):
'staticmethod': 'function',
'attribute': 'attribute',
}
+ indices = []
class NumpyCDomain(ManglingDomainBase, CDomain):
name = 'np-c'
diff --git a/doc/sphinxext/phantom_import.py b/doc/sphinxext/numpydoc/phantom_import.py
similarity index 95%
rename from doc/sphinxext/phantom_import.py
rename to doc/sphinxext/numpydoc/phantom_import.py
index c77eeb544e78bd38e9f32b5315026061c9c8a483..9a60b4a35b18f80bd88ca7f0bd63d0a39b272fe6 100644
--- a/doc/sphinxext/phantom_import.py
+++ b/doc/sphinxext/numpydoc/phantom_import.py
@@ -14,6 +14,8 @@ without needing to rebuild the documented module.
.. [1] http://code.google.com/p/pydocweb
"""
+from __future__ import division, absolute_import, print_function
+
import imp, sys, compiler, types, os, inspect, re
def setup(app):
@@ -23,7 +25,7 @@ def setup(app):
def initialize(app):
fn = app.config.phantom_import_file
if (fn and os.path.isfile(fn)):
- print "[numpydoc] Phantom importing modules from", fn, "..."
+ print("[numpydoc] Phantom importing modules from", fn, "...")
import_phantom_module(fn)
#------------------------------------------------------------------------------
@@ -129,7 +131,10 @@ def import_phantom_module(xml_file):
doc = "%s%s\n\n%s" % (funcname, argspec, doc)
obj = lambda: 0
obj.__argspec_is_invalid_ = True
- obj.func_name = funcname
+ if sys.version_info[0] >= 3:
+ obj.__name__ = funcname
+ else:
+ obj.func_name = funcname
obj.__name__ = name
obj.__doc__ = doc
if inspect.isclass(object_cache[parent]):
diff --git a/doc/sphinxext/plot_directive.py b/doc/sphinxext/numpydoc/plot_directive.py
similarity index 97%
rename from doc/sphinxext/plot_directive.py
rename to doc/sphinxext/numpydoc/plot_directive.py
index 80801e7986dc6ad55f6d57a596e85df0e1c2fab8..2014f857076c16647afe3fa5d3899abbb5105197 100644
--- a/doc/sphinxext/plot_directive.py
+++ b/doc/sphinxext/numpydoc/plot_directive.py
@@ -36,7 +36,7 @@ The ``plot`` directive supports the options
include-source : bool
Whether to display the source code. Default can be changed in conf.py
-
+
and the ``image`` directive options ``alt``, ``height``, ``width``,
``scale``, ``align``, ``class``.
@@ -74,10 +74,16 @@ TODO
to make them appear side-by-side, or in floats.
"""
+from __future__ import division, absolute_import, print_function
-import sys, os, glob, shutil, imp, warnings, cStringIO, re, textwrap, traceback
+import sys, os, glob, shutil, imp, warnings, re, textwrap, traceback
import sphinx
+if sys.version_info[0] >= 3:
+ from io import StringIO
+else:
+ from io import StringIO
+
import warnings
warnings.warn("A plot_directive module is also available under "
"matplotlib.sphinxext; expect this numpydoc.plot_directive "
@@ -94,7 +100,7 @@ def setup(app):
setup.app = app
setup.config = app.config
setup.confdir = app.confdir
-
+
app.add_config_value('plot_pre_code', '', True)
app.add_config_value('plot_include_source', False, True)
app.add_config_value('plot_formats', ['png', 'hires.png', 'pdf'], True)
@@ -257,7 +263,7 @@ def run(arguments, content, options, state_machine, state, lineno):
# is it in doctest format?
is_doctest = contains_doctest(code)
- if options.has_key('format'):
+ if 'format' in options:
if options['format'] == 'python':
is_doctest = False
else:
@@ -291,7 +297,7 @@ def run(arguments, content, options, state_machine, state, lineno):
results = makefig(code, source_file_name, build_dir, output_base,
config)
errors = []
- except PlotError, err:
+ except PlotError as err:
reporter = state.memo.reporter
sm = reporter.system_message(
2, "Exception occurred in plotting %s: %s" % (output_base, err),
@@ -314,7 +320,7 @@ def run(arguments, content, options, state_machine, state, lineno):
else:
source_code = ""
- opts = [':%s: %s' % (key, val) for key, val in options.items()
+ opts = [':%s: %s' % (key, val) for key, val in list(options.items())
if key in ('alt', 'height', 'width', 'scale', 'align', 'class')]
only_html = ".. only:: html"
@@ -444,7 +450,7 @@ def run_code(code, code_path, ns=None):
# Redirect stdout
stdout = sys.stdout
- sys.stdout = cStringIO.StringIO()
+ sys.stdout = StringIO()
# Reset sys.argv
old_sys_argv = sys.argv
@@ -456,9 +462,9 @@ def run_code(code, code_path, ns=None):
if ns is None:
ns = {}
if not ns:
- exec setup.config.plot_pre_code in ns
- exec code in ns
- except (Exception, SystemExit), err:
+ exec(setup.config.plot_pre_code, ns)
+ exec(code, ns)
+ except (Exception, SystemExit) as err:
raise PlotError(traceback.format_exc())
finally:
os.chdir(pwd)
@@ -520,7 +526,7 @@ def makefig(code, code_path, output_dir, output_base, config):
all_exists = True
for i, code_piece in enumerate(code_pieces):
images = []
- for j in xrange(1000):
+ for j in range(1000):
img = ImageFile('%s_%02d_%02d' % (output_base, i, j), output_dir)
for format, dpi in formats:
if out_of_date(code_path, img.filename(format)):
@@ -565,7 +571,7 @@ def makefig(code, code_path, output_dir, output_base, config):
for format, dpi in formats:
try:
figman.canvas.figure.savefig(img.filename(format), dpi=dpi)
- except exceptions.BaseException, err:
+ except exceptions.BaseException as err:
raise PlotError(traceback.format_exc())
img.formats.append(format)
diff --git a/doc/sphinxext/numpydoc/tests/test_docscrape.py b/doc/sphinxext/numpydoc/tests/test_docscrape.py
new file mode 100644
index 0000000000000000000000000000000000000000..b682504e1618f2436715a1512bf0b3d0e0cc4906
--- /dev/null
+++ b/doc/sphinxext/numpydoc/tests/test_docscrape.py
@@ -0,0 +1,767 @@
+# -*- encoding:utf-8 -*-
+from __future__ import division, absolute_import, print_function
+
+import sys, textwrap
+
+from numpydoc.docscrape import NumpyDocString, FunctionDoc, ClassDoc
+from numpydoc.docscrape_sphinx import SphinxDocString, SphinxClassDoc
+from nose.tools import *
+
+if sys.version_info[0] >= 3:
+ sixu = lambda s: s
+else:
+ sixu = lambda s: unicode(s, 'unicode_escape')
+
+
+doc_txt = '''\
+ numpy.multivariate_normal(mean, cov, shape=None, spam=None)
+
+ Draw values from a multivariate normal distribution with specified
+ mean and covariance.
+
+ The multivariate normal or Gaussian distribution is a generalisation
+ of the one-dimensional normal distribution to higher dimensions.
+
+ Parameters
+ ----------
+ mean : (N,) ndarray
+ Mean of the N-dimensional distribution.
+
+ .. math::
+
+ (1+2+3)/3
+
+ cov : (N, N) ndarray
+ Covariance matrix of the distribution.
+ shape : tuple of ints
+ Given a shape of, for example, (m,n,k), m*n*k samples are
+ generated, and packed in an m-by-n-by-k arrangement. Because
+ each sample is N-dimensional, the output shape is (m,n,k,N).
+
+ Returns
+ -------
+ out : ndarray
+ The drawn samples, arranged according to `shape`. If the
+ shape given is (m,n,...), then the shape of `out` is is
+ (m,n,...,N).
+
+ In other words, each entry ``out[i,j,...,:]`` is an N-dimensional
+ value drawn from the distribution.
+ list of str
+ This is not a real return value. It exists to test
+ anonymous return values.
+
+ Other Parameters
+ ----------------
+ spam : parrot
+ A parrot off its mortal coil.
+
+ Raises
+ ------
+ RuntimeError
+ Some error
+
+ Warns
+ -----
+ RuntimeWarning
+ Some warning
+
+ Warnings
+ --------
+ Certain warnings apply.
+
+ Notes
+ -----
+ Instead of specifying the full covariance matrix, popular
+ approximations include:
+
+ - Spherical covariance (`cov` is a multiple of the identity matrix)
+ - Diagonal covariance (`cov` has non-negative elements only on the diagonal)
+
+ This geometrical property can be seen in two dimensions by plotting
+ generated data-points:
+
+ >>> mean = [0,0]
+ >>> cov = [[1,0],[0,100]] # diagonal covariance, points lie on x or y-axis
+
+ >>> x,y = multivariate_normal(mean,cov,5000).T
+ >>> plt.plot(x,y,'x'); plt.axis('equal'); plt.show()
+
+ Note that the covariance matrix must be symmetric and non-negative
+ definite.
+
+ References
+ ----------
+ .. [1] A. Papoulis, "Probability, Random Variables, and Stochastic
+ Processes," 3rd ed., McGraw-Hill Companies, 1991
+ .. [2] R.O. Duda, P.E. Hart, and D.G. Stork, "Pattern Classification,"
+ 2nd ed., Wiley, 2001.
+
+ See Also
+ --------
+ some, other, funcs
+ otherfunc : relationship
+
+ Examples
+ --------
+ >>> mean = (1,2)
+ >>> cov = [[1,0],[1,0]]
+ >>> x = multivariate_normal(mean,cov,(3,3))
+ >>> print x.shape
+ (3, 3, 2)
+
+ The following is probably true, given that 0.6 is roughly twice the
+ standard deviation:
+
+ >>> print list( (x[0,0,:] - mean) < 0.6 )
+ [True, True]
+
+ .. index:: random
+ :refguide: random;distributions, random;gauss
+
+ '''
+doc = NumpyDocString(doc_txt)
+
+
+def test_signature():
+ assert doc['Signature'].startswith('numpy.multivariate_normal(')
+ assert doc['Signature'].endswith('spam=None)')
+
+def test_summary():
+ assert doc['Summary'][0].startswith('Draw values')
+ assert doc['Summary'][-1].endswith('covariance.')
+
+def test_extended_summary():
+ assert doc['Extended Summary'][0].startswith('The multivariate normal')
+
+def test_parameters():
+ assert_equal(len(doc['Parameters']), 3)
+ assert_equal([n for n,_,_ in doc['Parameters']], ['mean','cov','shape'])
+
+ arg, arg_type, desc = doc['Parameters'][1]
+ assert_equal(arg_type, '(N, N) ndarray')
+ assert desc[0].startswith('Covariance matrix')
+ assert doc['Parameters'][0][-1][-2] == ' (1+2+3)/3'
+
+def test_other_parameters():
+ assert_equal(len(doc['Other Parameters']), 1)
+ assert_equal([n for n,_,_ in doc['Other Parameters']], ['spam'])
+ arg, arg_type, desc = doc['Other Parameters'][0]
+ assert_equal(arg_type, 'parrot')
+ assert desc[0].startswith('A parrot off its mortal coil')
+
+def test_returns():
+ assert_equal(len(doc['Returns']), 2)
+ arg, arg_type, desc = doc['Returns'][0]
+ assert_equal(arg, 'out')
+ assert_equal(arg_type, 'ndarray')
+ assert desc[0].startswith('The drawn samples')
+ assert desc[-1].endswith('distribution.')
+
+ arg, arg_type, desc = doc['Returns'][1]
+ assert_equal(arg, 'list of str')
+ assert_equal(arg_type, '')
+ assert desc[0].startswith('This is not a real')
+ assert desc[-1].endswith('anonymous return values.')
+
+def test_notes():
+ assert doc['Notes'][0].startswith('Instead')
+ assert doc['Notes'][-1].endswith('definite.')
+ assert_equal(len(doc['Notes']), 17)
+
+def test_references():
+ assert doc['References'][0].startswith('..')
+ assert doc['References'][-1].endswith('2001.')
+
+def test_examples():
+ assert doc['Examples'][0].startswith('>>>')
+ assert doc['Examples'][-1].endswith('True]')
+
+def test_index():
+ assert_equal(doc['index']['default'], 'random')
+ assert_equal(len(doc['index']), 2)
+ assert_equal(len(doc['index']['refguide']), 2)
+
+def non_blank_line_by_line_compare(a,b):
+ a = textwrap.dedent(a)
+ b = textwrap.dedent(b)
+ a = [l.rstrip() for l in a.split('\n') if l.strip()]
+ b = [l.rstrip() for l in b.split('\n') if l.strip()]
+ for n,line in enumerate(a):
+ if not line == b[n]:
+ raise AssertionError("Lines %s of a and b differ: "
+ "\n>>> %s\n<<< %s\n" %
+ (n,line,b[n]))
+def test_str():
+ non_blank_line_by_line_compare(str(doc),
+"""numpy.multivariate_normal(mean, cov, shape=None, spam=None)
+
+Draw values from a multivariate normal distribution with specified
+mean and covariance.
+
+The multivariate normal or Gaussian distribution is a generalisation
+of the one-dimensional normal distribution to higher dimensions.
+
+Parameters
+----------
+mean : (N,) ndarray
+ Mean of the N-dimensional distribution.
+
+ .. math::
+
+ (1+2+3)/3
+
+cov : (N, N) ndarray
+ Covariance matrix of the distribution.
+shape : tuple of ints
+ Given a shape of, for example, (m,n,k), m*n*k samples are
+ generated, and packed in an m-by-n-by-k arrangement. Because
+ each sample is N-dimensional, the output shape is (m,n,k,N).
+
+Returns
+-------
+out : ndarray
+ The drawn samples, arranged according to `shape`. If the
+ shape given is (m,n,...), then the shape of `out` is is
+ (m,n,...,N).
+
+ In other words, each entry ``out[i,j,...,:]`` is an N-dimensional
+ value drawn from the distribution.
+list of str
+ This is not a real return value. It exists to test
+ anonymous return values.
+
+Other Parameters
+----------------
+spam : parrot
+ A parrot off its mortal coil.
+
+Raises
+------
+RuntimeError
+ Some error
+
+Warns
+-----
+RuntimeWarning
+ Some warning
+
+Warnings
+--------
+Certain warnings apply.
+
+See Also
+--------
+`some`_, `other`_, `funcs`_
+
+`otherfunc`_
+ relationship
+
+Notes
+-----
+Instead of specifying the full covariance matrix, popular
+approximations include:
+
+ - Spherical covariance (`cov` is a multiple of the identity matrix)
+ - Diagonal covariance (`cov` has non-negative elements only on the diagonal)
+
+This geometrical property can be seen in two dimensions by plotting
+generated data-points:
+
+>>> mean = [0,0]
+>>> cov = [[1,0],[0,100]] # diagonal covariance, points lie on x or y-axis
+
+>>> x,y = multivariate_normal(mean,cov,5000).T
+>>> plt.plot(x,y,'x'); plt.axis('equal'); plt.show()
+
+Note that the covariance matrix must be symmetric and non-negative
+definite.
+
+References
+----------
+.. [1] A. Papoulis, "Probability, Random Variables, and Stochastic
+ Processes," 3rd ed., McGraw-Hill Companies, 1991
+.. [2] R.O. Duda, P.E. Hart, and D.G. Stork, "Pattern Classification,"
+ 2nd ed., Wiley, 2001.
+
+Examples
+--------
+>>> mean = (1,2)
+>>> cov = [[1,0],[1,0]]
+>>> x = multivariate_normal(mean,cov,(3,3))
+>>> print x.shape
+(3, 3, 2)
+
+The following is probably true, given that 0.6 is roughly twice the
+standard deviation:
+
+>>> print list( (x[0,0,:] - mean) < 0.6 )
+[True, True]
+
+.. index:: random
+ :refguide: random;distributions, random;gauss""")
+
+
+def test_sphinx_str():
+ sphinx_doc = SphinxDocString(doc_txt)
+ non_blank_line_by_line_compare(str(sphinx_doc),
+"""
+.. index:: random
+ single: random;distributions, random;gauss
+
+Draw values from a multivariate normal distribution with specified
+mean and covariance.
+
+The multivariate normal or Gaussian distribution is a generalisation
+of the one-dimensional normal distribution to higher dimensions.
+
+:Parameters:
+
+ **mean** : (N,) ndarray
+
+ Mean of the N-dimensional distribution.
+
+ .. math::
+
+ (1+2+3)/3
+
+ **cov** : (N, N) ndarray
+
+ Covariance matrix of the distribution.
+
+ **shape** : tuple of ints
+
+ Given a shape of, for example, (m,n,k), m*n*k samples are
+ generated, and packed in an m-by-n-by-k arrangement. Because
+ each sample is N-dimensional, the output shape is (m,n,k,N).
+
+:Returns:
+
+ **out** : ndarray
+
+ The drawn samples, arranged according to `shape`. If the
+ shape given is (m,n,...), then the shape of `out` is is
+ (m,n,...,N).
+
+ In other words, each entry ``out[i,j,...,:]`` is an N-dimensional
+ value drawn from the distribution.
+
+ list of str
+
+ This is not a real return value. It exists to test
+ anonymous return values.
+
+:Other Parameters:
+
+ **spam** : parrot
+
+ A parrot off its mortal coil.
+
+:Raises:
+
+ **RuntimeError**
+
+ Some error
+
+:Warns:
+
+ **RuntimeWarning**
+
+ Some warning
+
+.. warning::
+
+ Certain warnings apply.
+
+.. seealso::
+
+ :obj:`some`, :obj:`other`, :obj:`funcs`
+
+ :obj:`otherfunc`
+ relationship
+
+.. rubric:: Notes
+
+Instead of specifying the full covariance matrix, popular
+approximations include:
+
+ - Spherical covariance (`cov` is a multiple of the identity matrix)
+ - Diagonal covariance (`cov` has non-negative elements only on the diagonal)
+
+This geometrical property can be seen in two dimensions by plotting
+generated data-points:
+
+>>> mean = [0,0]
+>>> cov = [[1,0],[0,100]] # diagonal covariance, points lie on x or y-axis
+
+>>> x,y = multivariate_normal(mean,cov,5000).T
+>>> plt.plot(x,y,'x'); plt.axis('equal'); plt.show()
+
+Note that the covariance matrix must be symmetric and non-negative
+definite.
+
+.. rubric:: References
+
+.. [1] A. Papoulis, "Probability, Random Variables, and Stochastic
+ Processes," 3rd ed., McGraw-Hill Companies, 1991
+.. [2] R.O. Duda, P.E. Hart, and D.G. Stork, "Pattern Classification,"
+ 2nd ed., Wiley, 2001.
+
+.. only:: latex
+
+ [1]_, [2]_
+
+.. rubric:: Examples
+
+>>> mean = (1,2)
+>>> cov = [[1,0],[1,0]]
+>>> x = multivariate_normal(mean,cov,(3,3))
+>>> print x.shape
+(3, 3, 2)
+
+The following is probably true, given that 0.6 is roughly twice the
+standard deviation:
+
+>>> print list( (x[0,0,:] - mean) < 0.6 )
+[True, True]
+""")
+
+
+doc2 = NumpyDocString("""
+ Returns array of indices of the maximum values of along the given axis.
+
+ Parameters
+ ----------
+ a : {array_like}
+ Array to look in.
+ axis : {None, integer}
+ If None, the index is into the flattened array, otherwise along
+ the specified axis""")
+
+def test_parameters_without_extended_description():
+ assert_equal(len(doc2['Parameters']), 2)
+
+doc3 = NumpyDocString("""
+ my_signature(*params, **kwds)
+
+ Return this and that.
+ """)
+
+def test_escape_stars():
+ signature = str(doc3).split('\n')[0]
+ assert_equal(signature, 'my_signature(\*params, \*\*kwds)')
+
+doc4 = NumpyDocString(
+ """a.conj()
+
+ Return an array with all complex-valued elements conjugated.""")
+
+def test_empty_extended_summary():
+ assert_equal(doc4['Extended Summary'], [])
+
+doc5 = NumpyDocString(
+ """
+ a.something()
+
+ Raises
+ ------
+ LinAlgException
+ If array is singular.
+
+ Warns
+ -----
+ SomeWarning
+ If needed
+ """)
+
+def test_raises():
+ assert_equal(len(doc5['Raises']), 1)
+ name,_,desc = doc5['Raises'][0]
+ assert_equal(name,'LinAlgException')
+ assert_equal(desc,['If array is singular.'])
+
+def test_warns():
+ assert_equal(len(doc5['Warns']), 1)
+ name,_,desc = doc5['Warns'][0]
+ assert_equal(name,'SomeWarning')
+ assert_equal(desc,['If needed'])
+
+def test_see_also():
+ doc6 = NumpyDocString(
+ """
+ z(x,theta)
+
+ See Also
+ --------
+ func_a, func_b, func_c
+ func_d : some equivalent func
+ foo.func_e : some other func over
+ multiple lines
+ func_f, func_g, :meth:`func_h`, func_j,
+ func_k
+ :obj:`baz.obj_q`
+ :class:`class_j`: fubar
+ foobar
+ """)
+
+ assert len(doc6['See Also']) == 12
+ for func, desc, role in doc6['See Also']:
+ if func in ('func_a', 'func_b', 'func_c', 'func_f',
+ 'func_g', 'func_h', 'func_j', 'func_k', 'baz.obj_q'):
+ assert(not desc)
+ else:
+ assert(desc)
+
+ if func == 'func_h':
+ assert role == 'meth'
+ elif func == 'baz.obj_q':
+ assert role == 'obj'
+ elif func == 'class_j':
+ assert role == 'class'
+ else:
+ assert role is None
+
+ if func == 'func_d':
+ assert desc == ['some equivalent func']
+ elif func == 'foo.func_e':
+ assert desc == ['some other func over', 'multiple lines']
+ elif func == 'class_j':
+ assert desc == ['fubar', 'foobar']
+
+def test_see_also_print():
+ class Dummy(object):
+ """
+ See Also
+ --------
+ func_a, func_b
+ func_c : some relationship
+ goes here
+ func_d
+ """
+ pass
+
+ obj = Dummy()
+ s = str(FunctionDoc(obj, role='func'))
+ assert(':func:`func_a`, :func:`func_b`' in s)
+ assert(' some relationship' in s)
+ assert(':func:`func_d`' in s)
+
+doc7 = NumpyDocString("""
+
+ Doc starts on second line.
+
+ """)
+
+def test_empty_first_line():
+ assert doc7['Summary'][0].startswith('Doc starts')
+
+
+def test_no_summary():
+ str(SphinxDocString("""
+ Parameters
+ ----------"""))
+
+
+def test_unicode():
+ doc = SphinxDocString("""
+ öäöäöäöäöåååå
+
+ öäöäöäööäååå
+
+ Parameters
+ ----------
+ ååå : äää
+ ööö
+
+ Returns
+ -------
+ ååå : ööö
+ äää
+
+ """)
+ assert isinstance(doc['Summary'][0], str)
+ assert doc['Summary'][0] == 'öäöäöäöäöåååå'
+
+def test_plot_examples():
+ cfg = dict(use_plots=True)
+
+ doc = SphinxDocString("""
+ Examples
+ --------
+ >>> import matplotlib.pyplot as plt
+ >>> plt.plot([1,2,3],[4,5,6])
+ >>> plt.show()
+ """, config=cfg)
+ assert 'plot::' in str(doc), str(doc)
+
+ doc = SphinxDocString("""
+ Examples
+ --------
+ .. plot::
+
+ import matplotlib.pyplot as plt
+ plt.plot([1,2,3],[4,5,6])
+ plt.show()
+ """, config=cfg)
+ assert str(doc).count('plot::') == 1, str(doc)
+
+def test_class_members():
+
+ class Dummy(object):
+ """
+ Dummy class.
+
+ """
+ def spam(self, a, b):
+ """Spam\n\nSpam spam."""
+ pass
+ def ham(self, c, d):
+ """Cheese\n\nNo cheese."""
+ pass
+ @property
+ def spammity(self):
+ """Spammity index"""
+ return 0.95
+
+ class Ignorable(object):
+ """local class, to be ignored"""
+ pass
+
+ for cls in (ClassDoc, SphinxClassDoc):
+ doc = cls(Dummy, config=dict(show_class_members=False))
+ assert 'Methods' not in str(doc), (cls, str(doc))
+ assert 'spam' not in str(doc), (cls, str(doc))
+ assert 'ham' not in str(doc), (cls, str(doc))
+ assert 'spammity' not in str(doc), (cls, str(doc))
+ assert 'Spammity index' not in str(doc), (cls, str(doc))
+
+ doc = cls(Dummy, config=dict(show_class_members=True))
+ assert 'Methods' in str(doc), (cls, str(doc))
+ assert 'spam' in str(doc), (cls, str(doc))
+ assert 'ham' in str(doc), (cls, str(doc))
+ assert 'spammity' in str(doc), (cls, str(doc))
+
+ if cls is SphinxClassDoc:
+ assert '.. autosummary::' in str(doc), str(doc)
+ else:
+ assert 'Spammity index' in str(doc), str(doc)
+
+def test_duplicate_signature():
+ # Duplicate function signatures occur e.g. in ufuncs, when the
+ # automatic mechanism adds one, and a more detailed comes from the
+ # docstring itself.
+
+ doc = NumpyDocString(
+ """
+ z(x1, x2)
+
+ z(a, theta)
+ """)
+
+ assert doc['Signature'].strip() == 'z(a, theta)'
+
+
+class_doc_txt = """
+ Foo
+
+ Parameters
+ ----------
+ f : callable ``f(t, y, *f_args)``
+ Aaa.
+ jac : callable ``jac(t, y, *jac_args)``
+ Bbb.
+
+ Attributes
+ ----------
+ t : float
+ Current time.
+ y : ndarray
+ Current variable values.
+
+ Methods
+ -------
+ a
+ b
+ c
+
+ Examples
+ --------
+ For usage examples, see `ode`.
+"""
+
+def test_class_members_doc():
+ doc = ClassDoc(None, class_doc_txt)
+ non_blank_line_by_line_compare(str(doc),
+ """
+ Foo
+
+ Parameters
+ ----------
+ f : callable ``f(t, y, *f_args)``
+ Aaa.
+ jac : callable ``jac(t, y, *jac_args)``
+ Bbb.
+
+ Examples
+ --------
+ For usage examples, see `ode`.
+
+ Attributes
+ ----------
+ t : float
+ Current time.
+ y : ndarray
+ Current variable values.
+
+ Methods
+ -------
+ a
+
+ b
+
+ c
+
+ .. index::
+
+ """)
+
+def test_class_members_doc_sphinx():
+ doc = SphinxClassDoc(None, class_doc_txt)
+ non_blank_line_by_line_compare(str(doc),
+ """
+ Foo
+
+ :Parameters:
+
+ **f** : callable ``f(t, y, *f_args)``
+
+ Aaa.
+
+ **jac** : callable ``jac(t, y, *jac_args)``
+
+ Bbb.
+
+ .. rubric:: Examples
+
+ For usage examples, see `ode`.
+
+ .. rubric:: Attributes
+
+ === ==========
+ t (float) Current time.
+ y (ndarray) Current variable values.
+ === ==========
+
+ .. rubric:: Methods
+
+ === ==========
+ a
+ b
+ c
+ === ==========
+
+ """)
+
+if __name__ == "__main__":
+ import nose
+ nose.run()
diff --git a/doc/sphinxext/numpydoc/tests/test_linkcode.py b/doc/sphinxext/numpydoc/tests/test_linkcode.py
new file mode 100644
index 0000000000000000000000000000000000000000..340166a485fcdabf0bc7846f74dafd604bed4d4d
--- /dev/null
+++ b/doc/sphinxext/numpydoc/tests/test_linkcode.py
@@ -0,0 +1,5 @@
+from __future__ import division, absolute_import, print_function
+
+import numpydoc.linkcode
+
+# No tests at the moment...
diff --git a/doc/sphinxext/numpydoc/tests/test_phantom_import.py b/doc/sphinxext/numpydoc/tests/test_phantom_import.py
new file mode 100644
index 0000000000000000000000000000000000000000..173b5662b8df748cadd5439c5c4a423b6c0c5d13
--- /dev/null
+++ b/doc/sphinxext/numpydoc/tests/test_phantom_import.py
@@ -0,0 +1,5 @@
+from __future__ import division, absolute_import, print_function
+
+import numpydoc.phantom_import
+
+# No tests at the moment...
diff --git a/doc/sphinxext/numpydoc/tests/test_plot_directive.py b/doc/sphinxext/numpydoc/tests/test_plot_directive.py
new file mode 100644
index 0000000000000000000000000000000000000000..0e511fcbc1428c7d948d858b4a3dd476d95cec3e
--- /dev/null
+++ b/doc/sphinxext/numpydoc/tests/test_plot_directive.py
@@ -0,0 +1,5 @@
+from __future__ import division, absolute_import, print_function
+
+import numpydoc.plot_directive
+
+# No tests at the moment...
diff --git a/doc/sphinxext/numpydoc/tests/test_traitsdoc.py b/doc/sphinxext/numpydoc/tests/test_traitsdoc.py
new file mode 100644
index 0000000000000000000000000000000000000000..d36e5ddbd751fcb1076ecc7613e2285695fa6d9b
--- /dev/null
+++ b/doc/sphinxext/numpydoc/tests/test_traitsdoc.py
@@ -0,0 +1,5 @@
+from __future__ import division, absolute_import, print_function
+
+import numpydoc.traitsdoc
+
+# No tests at the moment...
diff --git a/doc/sphinxext/traitsdoc.py b/doc/sphinxext/numpydoc/traitsdoc.py
similarity index 92%
rename from doc/sphinxext/traitsdoc.py
rename to doc/sphinxext/numpydoc/traitsdoc.py
index 0fcf2c1cd38c90e2ad350e5dfc3acd1caf5cf329..596c54eb389a3c7279de5ac8279776e2d27ba556 100644
--- a/doc/sphinxext/traitsdoc.py
+++ b/doc/sphinxext/numpydoc/traitsdoc.py
@@ -13,18 +13,20 @@ for Traits is required.
.. [2] http://code.enthought.com/projects/traits/
"""
+from __future__ import division, absolute_import, print_function
import inspect
import os
import pydoc
+import collections
-import docscrape
-import docscrape_sphinx
-from docscrape_sphinx import SphinxClassDoc, SphinxFunctionDoc, SphinxDocString
+from . import docscrape
+from . import docscrape_sphinx
+from .docscrape_sphinx import SphinxClassDoc, SphinxFunctionDoc, SphinxDocString
-import numpydoc
+from . import numpydoc
-import comment_eater
+from . import comment_eater
class SphinxTraitsDoc(SphinxClassDoc):
def __init__(self, cls, modulename='', func_doc=SphinxFunctionDoc):
@@ -117,7 +119,7 @@ def get_doc_object(obj, what=None, config=None):
what = 'class'
elif inspect.ismodule(obj):
what = 'module'
- elif callable(obj):
+ elif isinstance(obj, collections.Callable):
what = 'function'
else:
what = 'object'
diff --git a/kwant/builder.py b/kwant/builder.py
index e09cdf9c7b07f077f32502696408e17d5c48844a..15b303f390b3eb70a7c8805fbde16952632d3c7b 100644
--- a/kwant/builder.py
+++ b/kwant/builder.py
@@ -378,8 +378,8 @@ class HermConjOfFunc(object):
class Lead(object):
"""Abstract base class for leads that can be attached to a `Builder`.
- Instance Variables
- ------------------
+ Attributes
+ ----------
interface : sequence of sites
"""
__metaclass__ = abc.ABCMeta
diff --git a/kwant/lattice.py b/kwant/lattice.py
index 15669ef22de9a82ad8fdac0422ed32db57af0451..3f99e7a30d050b9b3f0c78194068f2ed557ee3b1 100644
--- a/kwant/lattice.py
+++ b/kwant/lattice.py
@@ -67,8 +67,8 @@ class Polyatomic(object):
If the name of the lattice is given, the names of sublattices are
obtained by appending their number to the name of the lattice.
- Instance Variables
- ------------------
+ Attributes
+ ----------
sublattices : list of `Monatomic`
Sublattices belonging to this lattice.
diff --git a/kwant/physics/leads.py b/kwant/physics/leads.py
index d36345040f6acc27a88256dbbd54c68909a079f1..d6efcad06d37639ae62042f3622dd2e40f289297 100644
--- a/kwant/physics/leads.py
+++ b/kwant/physics/leads.py
@@ -27,8 +27,8 @@ Linsys = namedtuple('Linsys', ['eigenproblem', 'v', 'extract'])
class PropagatingModes(object):
"""The calculated propagating modes of a lead.
- Instance variables
- ==================
+ Attributes
+ ----------
wave_functions : numpy array
The wave functions of the propagating modes.
momenta : numpy array
@@ -79,8 +79,8 @@ class StabilizedModes(object):
orthogonalized, and all the propagating modes are normalized to carry unit
current. Finally the `sqrt_hop` attribute is `v sqrt(s)`.
- Instance variables
- ==================
+ Attributes
+ ----------
vecs : numpy array
Translation eigenvectors.
vecslmbdainv : numpy array
diff --git a/kwant/solvers/common.py b/kwant/solvers/common.py
index a14617d609180d26505a98edba9490a706b2673d..a6bdecdaed1f9a693bc82ac9ced86211b9731ab6 100644
--- a/kwant/solvers/common.py
+++ b/kwant/solvers/common.py
@@ -607,8 +607,8 @@ class SMatrix(BlockResult):
of data corresponding to particular leads are conveniently obtained by
`~SMatrix.submatrix`.
- Instance Variables
- ------------------
+ Attributes
+ ----------
data : NumPy array
a matrix containing all the requested matrix elements of the scattering
matrix.
@@ -651,8 +651,8 @@ class GreensFunction(BlockResult):
to particular leads are conveniently obtained by
`~GreensFunction.submatrix`.
- Instance Variables
- ------------------
+ Attributes
+ ----------
data : NumPy array
a matrix containing all the requested matrix elements of Green's
function.
diff --git a/kwant/system.py b/kwant/system.py
index 2b9a7bd47589a7c0a00b5c8fa91f5ca9a69bd0f9..8497b8111e013bd3720b74fd5f2ed42cfe571b7d 100644
--- a/kwant/system.py
+++ b/kwant/system.py
@@ -20,8 +20,8 @@ from . import physics, _system
class System(object):
"""Abstract general low-level system.
- Instance Variables
- ------------------
+ Attributes
+ ----------
graph : kwant.graph.CGraph
The system graph.
@@ -56,8 +56,8 @@ System.hamiltonian_submatrix = types.MethodType(
class FiniteSystem(System):
"""Abstract finite low-level system, possibly with leads.
- Instance Variables
- ------------------
+ Attributes
+ ----------
leads : sequence of leads
Each lead has to provide a method
``selfenergy(energy, args)``.
@@ -148,8 +148,8 @@ class InfiniteSystem(System):
An infinite system consists of an infinite series of identical cells.
Adjacent cells are connected by identical inter-cell hoppings.
- Instance Variables
- ------------------
+ Attributes
+ ----------
cell_size : integer
The number of sites in a single cell of the system.