ENH: numpydoc: Python 2 & 3 in single codebase, restructure as a package

14 files changed, 89 insertions, 47 deletions

diff --git a/doc/sphinxext/MANIFEST.in b/doc/sphinxext/MANIFEST.in
index f88ed785c..5176d485b 100644
--- a/doc/sphinxext/MANIFEST.in
+++ b/doc/sphinxext/MANIFEST.in
@@ -1,2 +1,2 @@
-recursive-include tests *.py
+recursive-include numpydoc/tests *.py
 include *.txt
diff --git a/doc/sphinxext/__init__.py b/doc/sphinxext/__init__.py
deleted file mode 100644
index ae9073bc4..000000000
--- 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 000000000..68dbbb00a
--- /dev/null
+++ b/doc/sphinxext/numpydoc/__init__.py
@@ -0,0 +1 @@
+from .numpydoc import setup
diff --git a/doc/sphinxext/comment_eater.py b/doc/sphinxext/numpydoc/comment_eater.py
index e11eea902..f84ca6934 100644
--- a/doc/sphinxext/comment_eater.py
+++ b/doc/sphinxext/numpydoc/comment_eater.py
@@ -1,10 +1,15 @@
-from cStringIO import StringIO
+import sys
+if sys.version_info[0] >= 3:
+    from io import StringIO
+else:
+    from cStringIO 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 +73,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()
 
diff --git a/doc/sphinxext/compiler_unparse.py b/doc/sphinxext/numpydoc/compiler_unparse.py
index ffcf51b35..385f61c58 100644
--- a/doc/sphinxext/compiler_unparse.py
+++ b/doc/sphinxext/numpydoc/compiler_unparse.py
@@ -12,11 +12,15 @@
 """
 
 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 cStringIO import StringIO
+
 def unparse(ast, single_line_functions=False):
-    s = cStringIO.StringIO()
+    s = StringIO()
     UnparseCompilerAst(ast, s, single_line_functions)
     return s.getvalue().lstrip()
 
diff --git a/doc/sphinxext/docscrape.py b/doc/sphinxext/numpydoc/docscrape.py
index b492b1ab8..1e9f6343a 100644
--- a/doc/sphinxext/docscrape.py
+++ b/doc/sphinxext/numpydoc/docscrape.py
@@ -2,13 +2,18 @@
 
 """
 
+import sys
 import inspect
 import textwrap
 import re
 import pydoc
-from StringIO import StringIO
 from warnings import warn
 
+if sys.version_info[0] >= 3:
+    from io import StringIO
+else:
+    from cStringIO import StringIO
+
 class Reader(object):
     """A line-based string reader.
 
@@ -113,7 +118,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
@@ -374,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))]
@@ -432,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
 
@@ -454,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)
 
diff --git a/doc/sphinxext/docscrape_sphinx.py b/doc/sphinxext/numpydoc/docscrape_sphinx.py
index e44e770ef..20e61920f 100644
--- a/doc/sphinxext/docscrape_sphinx.py
+++ b/doc/sphinxext/numpydoc/docscrape_sphinx.py
@@ -1,6 +1,6 @@
 import re, inspect, textwrap, pydoc
 import sphinx
-from docscrape import NumpyDocString, FunctionDoc, ClassDoc
+from .docscrape import NumpyDocString, FunctionDoc, ClassDoc
 
 class SphinxDocString(NumpyDocString):
     def __init__(self, docstring, config={}):
@@ -127,7 +127,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':
diff --git a/doc/sphinxext/linkcode.py b/doc/sphinxext/numpydoc/linkcode.py
index 670dfe15f..670dfe15f 100644
--- a/doc/sphinxext/linkcode.py
+++ b/doc/sphinxext/numpydoc/linkcode.py
diff --git a/doc/sphinxext/numpydoc.py b/doc/sphinxext/numpydoc/numpydoc.py
index 7679352c2..ec4884db7 100644
--- a/doc/sphinxext/numpydoc.py
+++ b/doc/sphinxext/numpydoc/numpydoc.py
@@ -21,8 +21,8 @@ import sphinx
 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
+import os, sys, re, pydoc
+from .docscrape_sphinx import get_doc_object, SphinxDocString
 from sphinx.util.compat import Directive
 import inspect
 
@@ -34,12 +34,16 @@ 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(u'^\\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), config=cfg)
-        lines[:] = unicode(doc).split(u"\n")
+        if sys.version_info[0] >= 3:
+            doc = str(doc)
+        else:
+            doc = str(doc).decode('utf-8')
+        lines[:] = doc.split(u"\n")
 
     if app.config.numpydoc_edit_link and hasattr(obj, '__name__') and \
            obj.__name__:
@@ -47,7 +51,7 @@ def mangle_docstrings(app, what, name, obj, options, lines,
             v = dict(full_name=u"%s.%s" % (obj.__module__, obj.__name__))
         else:
             v = dict(full_name=obj.__name__)
-        lines += [u'', u'.. htmlonly::', '']
+        lines += [u'', u'.. htmlonly::', u'']
         lines += [u'    %s' % x for x in
                   (app.config.numpydoc_edit_link % v).split("\n")]
 
@@ -55,7 +59,7 @@ def mangle_docstrings(app, what, name, obj, options, lines,
     references = []
     for line in lines:
         line = line.strip()
-        m = re.match(ur'^.. \[([a-z0-9_.-])\]', line, re.I)
+        m = re.match(u'^.. \\[([a-z0-9_.-])\\]', line, re.I)
         if m:
             references.append(m.group(1))
 
@@ -64,7 +68,7 @@ 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):
+                if re.match(u'^\\d+$', r):
                     new_r = u"R%d" % (reference_offset[0] + int(r))
                 else:
                     new_r = u"%s%d" % (r, reference_offset[0])
@@ -91,6 +95,9 @@ def mangle_signature(app, what, name, obj, options, sig, retann):
         return sig, u''
 
 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 +127,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)
 
diff --git a/doc/sphinxext/phantom_import.py b/doc/sphinxext/numpydoc/phantom_import.py
index c77eeb544..c1e1ce1d8 100644
--- a/doc/sphinxext/phantom_import.py
+++ b/doc/sphinxext/numpydoc/phantom_import.py
@@ -23,7 +23,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 +129,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
index 80801e798..dea1014ac 100644
--- a/doc/sphinxext/plot_directive.py
+++ b/doc/sphinxext/numpydoc/plot_directive.py
@@ -75,9 +75,14 @@ TODO
 
 """
 
-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 cStringIO import StringIO
+
 import warnings
 warnings.warn("A plot_directive module is also available under "
               "matplotlib.sphinxext; expect this numpydoc.plot_directive "
@@ -257,7 +262,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 +296,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 +319,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 +449,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 +461,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 +525,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 +570,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/tests/test_docscrape.py b/doc/sphinxext/numpydoc/tests/test_docscrape.py
index 2454d27f5..7514419ca 100644
--- a/doc/sphinxext/tests/test_docscrape.py
+++ b/doc/sphinxext/numpydoc/tests/test_docscrape.py
@@ -1,10 +1,9 @@
 # -*- encoding:utf-8 -*-
 
 import sys, os
-sys.path.append(os.path.join(os.path.dirname(__file__), '..'))
 
-from docscrape import NumpyDocString, FunctionDoc, ClassDoc
-from docscrape_sphinx import SphinxDocString, SphinxClassDoc
+from numpydoc.docscrape import NumpyDocString, FunctionDoc, ClassDoc
+from numpydoc.docscrape_sphinx import SphinxDocString, SphinxClassDoc
 from nose.tools import *
 
 doc_txt = '''\
@@ -165,7 +164,7 @@ def test_examples():
 
 def test_index():
     assert_equal(doc['index']['default'], 'random')
-    print doc['index']
+    print(doc['index'])
     assert_equal(len(doc['index']), 2)
     assert_equal(len(doc['index']['refguide']), 2)
 
@@ -556,7 +555,11 @@ def test_unicode():
         äää
 
     """)
-    assert doc['Summary'][0] == u'öäöäöäöäöåååå'.encode('utf-8')
+    assert isinstance(doc['Summary'][0], str)
+    if sys.version_info[0] >= 3:
+        assert doc['Summary'][0] == u'öäöäöäöäöåååå'
+    else:
+        assert doc['Summary'][0] == u'öäöäöäöäöåååå'.encode('utf-8')
 
 def test_plot_examples():
     cfg = dict(use_plots=True)
diff --git a/doc/sphinxext/traitsdoc.py b/doc/sphinxext/numpydoc/traitsdoc.py
index 0fcf2c1cd..952206c44 100644
--- a/doc/sphinxext/traitsdoc.py
+++ b/doc/sphinxext/numpydoc/traitsdoc.py
@@ -18,13 +18,13 @@ import inspect
 import os
 import pydoc
 
-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):
diff --git a/doc/sphinxext/setup.py b/doc/sphinxext/setup.py
index ec6aa3840..3dbcee5c8 100644
--- a/doc/sphinxext/setup.py
+++ b/doc/sphinxext/setup.py
@@ -1,11 +1,16 @@
+import setuptools
 from distutils.core import setup
 
-version = "0.4"
+import sys
+if sys.version_info[0] >= 3 and sys.version_info[1] < 3 or \
+        sys.version_info[0] <= 2 and sys.version_info[1] < 6:
+    raise RuntimeError("Python version 2.6, 2.7 or >= 3.3 required.")
+
+version = "0.4.dev"
 
 setup(
     name="numpydoc",
     packages=["numpydoc"],
-    package_dir={"numpydoc": "."},
     version=version,
     description="Sphinx extension to support docstrings in Numpy format",
     # classifiers from http://pypi.python.org/pypi?%3Aaction=list_classifiers
@@ -20,4 +25,5 @@ setup(
     license="BSD",
     requires=["sphinx (>= 1.0.1)"],
     package_data={'numpydoc': ['tests/test_*.py']},
+    test_suite = 'nose.collector',
 )