[Numpy-discussion] Sphinx custom extension mess, and patches

Gael Varoquaux gael.varoquaux@normalesup....
Sun Feb 15 08:04:00 CST 2009


Hi all,

Sorry for the multiple posting, this concerns various groups, and I'd
rather the information not be lost.

While working on getting our in-lab library ready to be merged with NiPy,
I ran into some sort of 'sphinx extension mess' where various sphinx
extension would have side effects on each other, and most important, the
extensions did not work with sphinx trunk.

I got the side effects to be limited by cleaning up the generated code
from autosummary before each run: I added the following code in my
sphinx conf.py:

################################################################################
# Hack: run the autosummary generation script 
import shutil
if os.path.exists('generated'):
    shutil.rmtree('generated')
os.system('%s sphinxext/autosummary_generate.py -o generated *.rst' %
            sys.executable)
################################################################################

I am attaching a diff of all the modifications I made to get the various
extensions to work. I hope you can use it to get your various extensions
working on sphinx trunk quicker. For the NiPy guys, I will be committing
these changes in the fff2 tree soon, and we can go over this at the
sprint.

This does raise a problem: this extension code is all over the place, in
various repository. Some of the code cannot live in the sphinx repo, as
it introduces dependencies. However, as the extensions are not importable
from Python (I can't do 'from matplotlib.sphinxext import mathmpl'), the
different projects using them end up copying them in their repo, and thus
there are several versions floating around not updated. Some of the
extensions would do not add externa dependencies to sphinx. These should
be pushed into sphinx, with tests. That way as sphinx evolves, they do
not break.

Gaël
-------------- next part --------------
=== modified file 'doc/sphinxext/autosummary.py'
--- doc/sphinxext/autosummary.py	2009-02-14 18:36:49 +0000
+++ doc/sphinxext/autosummary.py	2009-02-15 13:41:08 +0000
@@ -56,7 +56,7 @@
 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
@@ -160,6 +160,7 @@
         tocnode['includefiles'] = docnames
         tocnode['maxdepth'] = -1
         tocnode['glob'] = None
+        tocnode['entries'] = [] 
 
         tocnode = autosummary_toc('', '', tocnode)
         return warnings + [node] + [tocnode]

=== modified file 'doc/sphinxext/inheritance_diagram.py'
--- doc/sphinxext/inheritance_diagram.py	2009-02-14 18:36:49 +0000
+++ doc/sphinxext/inheritance_diagram.py	2009-02-15 12:53:28 +0000
@@ -40,7 +40,10 @@
 
 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
 from docutils.parsers.rst import directives
 from sphinx.roles import xfileref_role
 

=== modified file 'doc/sphinxext/mathmpl.py'
--- doc/sphinxext/mathmpl.py	2009-02-14 18:36:49 +0000
+++ doc/sphinxext/mathmpl.py	2009-02-15 12:45:33 +0000
@@ -7,7 +7,10 @@
 from docutils import nodes
 from docutils.parsers.rst import directives
 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
 
 # Define LaTeX math node:

=== modified file 'doc/sphinxext/only_directives.py'
--- doc/sphinxext/only_directives.py	2009-02-14 18:36:49 +0000
+++ doc/sphinxext/only_directives.py	2009-02-15 12:54:47 +0000
@@ -5,7 +5,10 @@
 
 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
 from docutils.parsers.rst import directives
 
 class html_only(Body, Element):



More information about the Numpy-discussion mailing list