ENH: Support calling Sphinx with Python 3

Update doc/source/conf.py to Python 3
Unbundle numpydoc, add to travis tests

STY: PEP8 style cleanup

Author: effigies

.travis.yml

@@ -107,7 +107,7 @@ script:
       COVER_ARGS="--with-coverage --cover-package nibabel";
       fi
     - if [ "$DOC_DOC_TEST" == "1" ]; then
-      pip install sphinx;
+      pip install sphinx numpydoc;
       cd ../doc;
       make html;
       make doctest;

doc/source/conf.py

@@ -11,45 +11,51 @@
 # nipype documentation build configuration file, created by
 # sphinx-quickstart on Mon Jul 20 12:30:18 2009.
 #
-# This file is execfile()d with the current directory set to its containing dir.
+# This file is exec()d with the current directory set to its containing dir.
 #
 # Note that not all possible configuration values are present in this
 # autogenerated file.
 #
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import sys
+import os
 
 import nibabel
 
+# Check for external Sphinx extensions we depend on
+try:
+    import numpydoc
+except ImportError:
+    raise RuntimeError('Need to install "numpydoc" package for doc build')
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.append(os.path.abspath('../sphinxext'))
 
-# -- General configuration -----------------------------------------------------
+# -- General configuration ----------------------------------------------------
 
 # We load the nibabel release info into a dict by explicit execution
 rel = {}
-execfile('../../nibabel/info.py', rel)
+with open(os.path.join('..', '..', 'nibabel', 'info.py'), 'r') as fobj:
+    exec(fobj.read(), rel)
 
 # Write long description from info
 with open('_long_description.inc', 'wt') as fobj:
     fobj.write(rel['LONG_DESCRIPTION'])
 
-# Add any Sphinx extension module names here, as strings. They can be extensions
-# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.doctest',
               #'sphinx.ext.intersphinx',
               'sphinx.ext.todo',
               'sphinx.ext.mathjax',
               'sphinx.ext.inheritance_diagram',
               'sphinx.ext.autosummary',
-              'math_dollar', # has to go before numpydoc
-              # we have a local copy of the extension, imported from NumPy 1.3
-              # this also includes the docscrape* extensions
+              'math_dollar',  # has to go before numpydoc
               'numpydoc',
               'only_directives',
               'plot_directive',
@@ -104,7 +110,7 @@
 # for source files.
 exclude_trees = ['_build']
 
-# The reST default role (used for this markup: `text`) to use for all documents.
+# The reST default role (used for this markup: `text`) to use for all documents
 #default_role = None
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
@@ -124,7 +130,7 @@
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
 
-# -- Sphinxext configuration ---------------------------------------------------
+# -- Sphinxext configuration --------------------------------------------------
 
 # Set attributes for layout of inheritance diagrams
 inheritance_graph_attrs = dict(rankdir="LR", size='"6.0, 8.0"', fontsize=14,
@@ -135,7 +141,7 @@
 # Flag to show todo items in rendered output
 todo_include_todos = True
 
-# -- Options for HTML output ---------------------------------------------------
+# -- Options for HTML output --------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
@@ -218,7 +224,7 @@
 
 mathjax_path = 'https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML'
 
-# -- Options for LaTeX output --------------------------------------------------
+# -- Options for LaTeX output -------------------------------------------------
 
 # The paper size ('letter' or 'a4').
 #latex_paper_size = 'letter'
@@ -227,11 +233,11 @@
 #latex_font_size = '10pt'
 
 # Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass [howto/manual]).
+# (source start file, target name, title, author,
+#  documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'nibabel.tex', u'NiBabel Documentation',
-   u'NiBabel Authors', 'manual'),
-]
+    ('index', 'nibabel.tex', u'NiBabel Documentation', u'NiBabel Authors',
+     'manual')]
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.