[SciPy-dev] Of use and abuse of sphinx's math directive

nicky van foreest vanforeest@gmail....
Wed Oct 29 08:53:51 CDT 2008


Suppose for later uses you want to export the documentation to some
format (e.g. latex, mediawiki (?) ) in which you like to make the
difference explicit between n and $n$. This would entail a lot of
searching. As an anecdote, Knuth used to write 1 rather than $1$. When
he developped the Euler font with Zapf, it turned out that 1 had a
different appearance than $1$. Knuth is Knuth, so he changed in all 1,
2, \ldots in one of his books that used the Euler font to $1$, $2$,



2008/10/28 Stéfan van der Walt <stefan@sun.ac.za>:
> 2008/10/28 Gael Varoquaux <gael.varoquaux@normalesup.org>:
>> Sphinx is great, will all love Sphinx. But I do wonder if sometimes we do
>> not use the math directive a bit too much, eg the "n" and "n-1" on:
>> http://scipy.org/scipy/scipy/browser/trunk/scipy/cluster/hierarchy.py#L1090
>> (this is just an example that I picked randomly).
>> When the formula written is simple-enought that its readibility is not
>> too much affected by having it in text in the Sphinxified document, I
>> think it is a pitty to render the plain text docstrings hard-to-read.
> Certainly -- the idea is to use the :math: tag sparingly.
> Cheers
> Stéfan
> _______________________________________________
> Scipy-dev mailing list
> Scipy-dev@scipy.org
> http://projects.scipy.org/mailman/listinfo/scipy-dev

More information about the Scipy-dev mailing list