[SciPy-dev] Latex and docstrings

[Ralf Gommers]

On Wed, Feb 17, 2010 at 6:22 PM, Tom Grydeland <tom.grydeland at gmail.com>wrote:

> On Wed, Feb 10, 2010 at 3:12 AM, David Cournapeau <david at silveregg.co.jp>
> wrote:
> > Hi,
> >
> > I noticed that some of the docstrings I have written for DCT have been
> > changed to latex format. While I have no issue with having latex in the
> > documentation, I thought the consensus was to use them sparingly in
> > docstrings ?
>
> I am probably the one to "blame" here.  I know I have edited the DCT
> docstrings.
>
> What is considered "sparingly" is obviously different from one person
> to the next, and I have taken it to mean roughly "where pure text is
> insufficient", and (along the discussion re numpy.fft and friends
> <http://docs.scipy.org/numpy/docs/numpy.fft/>) okay for module-level
> docstrings but avoid it for functions.
>

That's about right. In function docstrings latex should only sparingly be
used in the Notes section (see
http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines). This policy has
worked pretty well so far, the problem for this particular docstring is that
the Notes section is huge with lots of maths.

>
> > For example, the dct I formula used to be (fixed width font assumed):
> >
> > for 0 <= k < N,
> >
> >                                    N-1
> > y[k] = x[0] + (-1)**k x[N-1] + 2 * sum x[n]*cos(pi*k*n/(N-1))
> >                                    n=0
> >
> > But now, it is:
> >
> > y_k = x_0 + (-1)^k x_{N-1} + 2\\sum_{n=1}^{N-2} x_n
> >         \\cos\\left({\\pi nk\\over N-1}\\right),
> >         \\qquad 0 \\le k < N.
> >
> > I much prefer the former (the latter is unreadable in a terminal IMO). I
> > have of course no issue in putting the latex formula in the scipy docs,
>
> Similarly, the former is unreadable or incorrect in the web interface
> where the latter is useful:
> http://docs.scipy.org/scipy/docs/scipy.fftpack.realtransforms.dct/
>
> If you change it back, please observe that the limits on the summation
> are different for the two versions.


Fixing this docstring for both terminal and html/pdf does not seem possible,
short of removing content or writing a new Sphinx plugin. For now I would be
in favor of keeping the latex, because going to the html doc for terminal
users is doable. Users of the html docs on the other hand are unlikely to
all know their way around a terminal.

Cheers,
Ralf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20100217/1711d2c3/attachment.html>