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

[Michael Droettboom]

Gael,

You raise a very good point about the duplication of code around.  As a 
case in point, the patches you provided no longer apply to the 
"canonical" (or at least original) versions of the plugins that began 
life in matplotlib.  Recent versions of Sphinx have a proper extension 
API, so that "try ... except" importing is no longer necessary.

For mathmpl.py --- I will move that into the matplotlib installed code 
tree, so, as you suggest, "from matplotlib.sphinxext import mathmpl" 
will work.  Obviously, that won't really provide traction until the next 
release of matplotlib.  And it relies on only_directive.py, so I will 
probably have to put that in matplotlib as well for now, though that is 
a reasonable candidate for inclusion in Sphinx.

I have submitted inheritance_diagram.py to Sphinx already.  There didn't 
seem to be much interest, and there were some details (particularly how 
it deals with files), that weren't "the Sphinx way", and there few 
documents and/or examples etc. at the time about how to do it right.  
Someone else ended up re-engineering it to use pygraphviz which felt 
pretty heavy weight to me.  So the thing kind of stalled.  But it's 
probably worth another push.

Mike

Gael Varoquaux wrote:
> 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
>   
> ------------------------------------------------------------------------
>
> ------------------------------------------------------------------------------
> Open Source Business Conference (OSBC), March 24-25, 2009, San Francisco, CA
> -OSBC tackles the biggest issue in open source: Open Sourcing the Enterprise
> -Strategies to boost innovation and cut costs with open source participation
> -Receive a $600 discount off the registration fee with the source code: SFAD
> http://p.sf.net/sfu/XcvMzF8H
> ------------------------------------------------------------------------
>
> _______________________________________________
> Matplotlib-devel mailing list
> Matplotlib-devel at lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel

-- 
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA