sphinxext: Sphinx 0.6 compatibility and deprecation warnings

3 files changed, 24 insertions, 2 deletions

diff --git a/doc/sphinxext/autosummary.py b/doc/sphinxext/autosummary.py
index c32953ff5..f7e9a1291 100644
--- a/doc/sphinxext/autosummary.py
+++ b/doc/sphinxext/autosummary.py
@@ -56,11 +56,17 @@ from docutils.parsers.rst import directives
 from docutils.statemachine import ViewList
 from docutils import nodes
 
-import sphinx.addnodes, sphinx.roles, sphinx.builder
+import sphinx.addnodes, sphinx.roles
 from sphinx.util import patfilter
 
 from docscrape_sphinx import get_doc_object
 
+import warnings
+warnings.warn("This 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)
 
 def setup(app):
     app.add_directive('autosummary', autosummary_directive, True, (0, 0, False),
@@ -161,6 +167,7 @@ def autosummary_directive(dirname, arguments, options, content, lineno,
         tocnode['includefiles'] = docnames
         tocnode['maxdepth'] = -1
         tocnode['glob'] = None
+        tocnode['entries'] = [(None, docname) for docname in docnames]
 
         tocnode = autosummary_toc('', '', tocnode)
         return warnings + [node] + [tocnode]
diff --git a/doc/sphinxext/only_directives.py b/doc/sphinxext/only_directives.py
index e4dfd5cc7..c25760ad0 100644
--- a/doc/sphinxext/only_directives.py
+++ b/doc/sphinxext/only_directives.py
@@ -5,7 +5,16 @@
 
 from docutils.nodes import Body, Element
 from docutils.writers.html4css1 import HTMLTranslator
-from sphinx.latexwriter import LaTeXTranslator
+try:
+    from sphinx.latexwriter import LaTeXTranslator
+except ImportError:
+    from sphinx.writers.latex import LaTeXTranslator
+
+    import warnings
+    warnings.warn("The only_directives module is deprecated; please use "
+                  "the only:: directive available in Sphinx >= 0.6",
+                  DeprecationWarning, stacklevel=2)
+
 from docutils.parsers.rst import directives
 
 class html_only(Body, Element):
diff --git a/doc/sphinxext/plot_directive.py b/doc/sphinxext/plot_directive.py
index 6b5ff6eaf..74bd7a24b 100644
--- a/doc/sphinxext/plot_directive.py
+++ b/doc/sphinxext/plot_directive.py
@@ -74,6 +74,12 @@ TODO
 
 import sys, os, glob, shutil, imp, warnings, cStringIO, re, textwrap
 
+import warnings
+warnings.warn("A plot_directive module is also available under "
+              "matplotlib.sphinxext; expect this module to be deprecated "
+              "after relevant features have been integrated there.",
+              FutureWarning, stacklevel=2)
+
 def setup(app):
     setup.app = app
     setup.config = app.config