merge doc changes from numpy

ddale · ddale · commit 01703ad7b822 · 2009-04-14T08:56:23.000-04:00
diff --git 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
@@ -13,19 +13,29 @@
 
 import sys, os
 
-# 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.
-extensions = ['sphinx.ext.pngmath', 'sphinx.ext.autodoc', 
-              'ipython_console_highlighting', 'plot_directive', 'numpydoc',
-              'docscrape', 'docscrape_sphinx', 'autosummary']
+
+sys.path.append(os.path.abspath('../sphinxext'))
+
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.pngmath', 'numpydoc',
+              'sphinx.ext.intersphinx', 'sphinx.ext.coverage',
+              'only_directives']
+
+if sphinx.__version__ >= "0.7":
+    extensions.append('sphinx.ext.autosummary')
+    import glob
+    autosummary_generate = glob.glob("reference/*.rst")
+else:
+    extensions.append('autosummary')
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
diff --git a/doc/sphinxext/autosummary.py b/doc/sphinxext/autosummary.py
@@ -62,11 +62,12 @@
 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),
