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:[EMAIL PROTECTED] > Sent: Thursday, September 11, 2008 5:50 AM > To: Ted Drain > Cc: matplotlib-devel@lists.sourceforge.net > 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 ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
