[matplotlib-devel] Sphinx custom extension mess, and patches

[Gael V. <gae...@no...>]

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