[SciPy-dev] Latex and docstrings

Robert Kern robert.kern@gmail....
Wed Feb 17 10:05:03 CST 2010

On Wed, Feb 17, 2010 at 04:22, Tom Grydeland <tom.grydeland@gmail.com> wrote:
> On Wed, Feb 10, 2010 at 3:12 AM, David Cournapeau <david@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``)::

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

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

More information about the SciPy-Dev mailing list