Re: [matplotlib-devel] Question about sphinx doc extensions

[Ted D. <ted...@jp...>]

Mike,
Thanks for the info.  I noticed in plot_directive.py that ipython seems to
be required to build the docs.  Is that absolutely needed or is it a
holdover from doing something else?  I'm asking because we would like to
build the docs locally but don't currently install ipython.  I could change
that but it's just an artifact of something else it might be better to
remove that dependency.

Ted

> -----Original Message-----
> From: Michael Droettboom [mailto:md...@st...]
> Sent: Thursday, September 11, 2008 5:50 AM
> To: Ted Drain
> Cc: mat...@li...
> Subject: Re: [matplotlib-devel] Question about sphinx doc extensions
> 
> Ted Drain wrote:
> > We're in the process of converting our documentation from doxygen
> (parsing C++ and post processing w/ many huge regexp's to make it look
> like python) to using sphinx.  I was curious about the equation
> formatting extension that you guys wrote and how it compares to the one
> (or is it two?) that come with sphinx.
> Sphinx can a) use jsmath to render math directly in the browser, b) use
> latex/dvipng to generate images that are included in the HTML.
> Matplotlib's mplmath extension uses matplotlib itself to generate
> images
> of the math to include in the HTML.  All of them have pros and cons,
> mostly related to environment/installation concerns.  The extensions
> are
> generally interchangable (you should be able to use any one of them on
> the same reST source code), however the mplmath extension is currently
> lagging behind the Sphinx ones in some optional features at the moment.
> But our goal is to try to not break compatibility with the Sphinx
> built-in ones so they remain interchangeable.
> >   What didn't work about the sphinx math extensions that caused you
> to write a new one?
> When we wrote ours, a Sphinx math extension didn't exist.  Also, for
> us,
> generating math expressions using our own system is a form of
> regression
> testing.
> >  Are there any plans to incorporate some of the MPL extensions into
> sphinx?
> >
> We've submitted all of our generally useful ones to Sphinx.  For math,
> Sphinx decided to go another way (which makes sense to avoid a
> dependency on matplotlib).
> 
> The inheritance diagram submission seems to have stalled -- there are a
> few people with slightly different views on the problem creating a bit
> of a logjam, but I don't think it's insurmountable.
> 
> Lastly, the ipython syntax-highlighting work we did is in Pygments
> repository and primed for the next release.
> > We'll definitely need latex equations, testing of examples (maybe
> some combination of the MPL plot and doctest like functions), and
> inheritance diagrams so we might just use the MPL sphinx extensions for
> these.
> >
> > We're also planning on making some custom html templates to make our
> output more like doxygen (especially having a class summary showing all
> the methods at the top of the screen).  We may also look at processing
> our users guide, our python module, matplotlib, python, and any other
> 3rd party package we install that uses sphinx (and maybe some that
> don't) to create a single set of docs showing all the python modules we
> deliver that has a common look to it.
> >
> I'd like to hear about your experiences doing this kind of integration
> work.  It's something we all want more of.
> 
> Cheers,
> Mike
> 
> --
> Michael Droettboom
> Science Software Branch
> Operations and Engineering Division
> Space Telescope Science Institute
> Operated by AURA for NASA
> 
> Checked by AVG - http://www.avg.com
> Version: 8.0.169 / Virus Database: 270.6.20/1666 - Release Date:
> 9/11/2008 7:03 AM