[SciPy-dev] Latex and docstrings

[Charles R Harris]

On Wed, Feb 17, 2010 at 5:21 AM, Ralf Gommers
<ralf.gommers at googlemail.com>wrote:

>
>
> 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.
>
>
I don't think the docstrings should be tutorials, rather, they should state
what the function does in simple terms. A place for more extended
explanation might be desirable at some point for teaching purposes but I
don't think it belongs in the docstrings.

Chuck
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20100217/57d54687/attachment.html>