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 ------------------------------------------------------------------------- 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
