[SciPy-dev] Latex and docstrings

[Robert Kern]

On Wed, Feb 17, 2010 at 04:22, 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.  Since I have written a lot of
> latex, I might have a lower threshold than others here.
>
>> 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/

The former can be returned to readable in the web interface simply by
using the "::" literal marker at the end of the previous line. E.g.

"""
There are several definitions of the DCT-I; we use the following
(for ``norm=None``)::

                                     N-2
  y[k] = x[0] + (-1)**k x[N-1] + 2 * sum x[n]*cos(pi*k*n/(N-1))
                                     n=0
"""

Additionally, the font on the edit box should be monospaced to assist
editors in editing the docstrings to look good in plain text. I'll
look into changing that.

-- 
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless
enigma that is made terrible by our own mad attempt to interpret it as
though it had an underlying truth."
  -- Umberto Eco