[Numpy-discussion] math directive, rest files and sphinx

[Pauli Virtanen]

Tue, 16 Sep 2008 23:09:18 +0900, David Cournapeau wrote:
> Stéfan van der Walt wrote:
[clip]
>> While I like the mathml approach, it does not render perfectly on all
>> browsers and, as you've discovered, doesn't support all the constructs.
>>  It may be easier to switch to the math module now in Sphinx, rather
>> than to update the mathml module.  I'll leave the decision up to Pauli
>> and yourself;
> 
> I don't think I am entitled to make any decision here: I have no
> knowledge of the stack involved here. I can only confirm than using
> sphinx 0.5 (the dev version) does work for latex constructs; I could not
> make the JS backend work, but again, I know nothing about web frameworks
> and co, and I guess setting up a webserver for this to work to be
> trivial for anyone who knows his stuff here.

I believe the most forward-proof and downwards-compatible way for us is 
to switch to sphinx.ext.pngmath, and rely on Sphinx 0.5.dev. (0.5 also 
has the cool Intersphinx extension, using which we can easily link eg. to 
Python docs, or from scipy docs to numpy docs.)

The current mathml code could perhaps also be polished a bit and 
contributed to sphinx.ext as an extra math back-end. The pngmath and 
jsmath backends share some code that do part of the work, so the current 
code would need to be tweaked a bit.

-- 
Pauli Virtanen