Deprecating sphinxext/autosummary in favor of the version in Sphinx >= 0.7

3 files changed, 27 insertions, 13 deletions

diff --git a/doc/Makefile b/doc/Makefile
index 47ee1fb01..d0012fff2 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -9,6 +9,8 @@ SPHINXOPTS    =
 SPHINXBUILD   = LANG=C sphinx-build
 PAPER         =
 
+NEED_AUTOSUMMARY = $(shell $(PYTHON) -c 'import sphinx; print sphinx.__version__ >= "0.7" and "1" or ""')
+
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
@@ -95,9 +97,11 @@ dist-build:
 generate: build/generate-stamp
 build/generate-stamp: $(wildcard source/reference/*.rst)
 	mkdir -p build
+ifeq ($(NEED_AUTOSUMMARY),1)
 	$(PYTHON) \
 		./sphinxext/autosummary_generate.py source/reference/*.rst \
 		-p dump.xml -o source/reference/generated 
+endif
 	touch build/generate-stamp
 
 html: generate
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 6261bd8bb..d5ab2cd78 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -2,26 +2,28 @@
 
 import sys, os, re
 
-# If your extensions are in another directory, add it 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'))
-
 # Check Sphinx version
 import sphinx
 if sphinx.__version__ < "0.5":
     raise RuntimeError("Sphinx 0.5.dev or newer required")
 
-
 # -----------------------------------------------------------------------------
 # General configuration
 # -----------------------------------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+
+sys.path.append(os.path.abspath('../sphinxext'))
+
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.pngmath', 'numpydoc',
-              'phantom_import', 'autosummary', 'sphinx.ext.intersphinx',
-              'sphinx.ext.coverage', 'only_directives']
+              'sphinx.ext.intersphinx', 'sphinx.ext.coverage',
+              'only_directives']
+
+if sphinx.__version__ >= "0.7":
+    extensions.append('sphinx.ext.autosummary')
+else:
+    extensions.append('autosummary')
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -211,6 +213,13 @@ intersphinx_mapping = {'http://docs.python.org/dev': None}
 phantom_import_file = 'dump.xml'
 
 # -----------------------------------------------------------------------------
+# Autosummary
+# -----------------------------------------------------------------------------
+
+import glob
+autosummary_generate = glob.glob("reference/*.rst")
+
+# -----------------------------------------------------------------------------
 # Coverage checker
 # -----------------------------------------------------------------------------
 coverage_ignore_modules = r"""
diff --git a/doc/sphinxext/autosummary.py b/doc/sphinxext/autosummary.py
index 4e64a8d05..2f8a00a30 100644
--- a/doc/sphinxext/autosummary.py
+++ b/doc/sphinxext/autosummary.py
@@ -62,11 +62,12 @@ from sphinx.util import patfilter
 from docscrape_sphinx import get_doc_object
 
 import warnings
-warnings.warn("The numpydoc.autosummary extension will be eventually moved to "
-              "sphinx.ext.autosummary. One version is already available in "
-              "Sphinx >= 0.6; expect this module to be deprecated after all "
-              "remaining features have been integrated there.",
-              FutureWarning, stacklevel=2)
+warnings.warn(
+    "The numpydoc.autosummary extension can also be found as "
+    "sphinx.ext.autosummary in Sphinx >= 0.6, and the version in "
+    "Sphinx >= 0.7 is superior to the one in numpydoc. This numpydoc "
+    "version of autosummary is no longer maintained.",
+    DeprecationWarning, stacklevel=2)
 
 def setup(app):
     app.add_directive('autosummary', autosummary_directive, True, (0, 0, False),