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

[David Cournapeau]

On Wed, Oct 29, 2008 at 10:53 PM, nicky van foreest
<vanforeest at gmail.com> wrote:
> Hi,
>
> 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$,
> etc.

I am not sure the comparison is accurate: docstrings are not meant to
be edition-ready. They are meant to be read from the interpreter
mainly; for help meant to be put in a general documentation, I think
separate doc is better, and there you can go crazy about  latex and
co.

David