[SciPy-dev] Latex and docstrings
Tom Grydeland
tom.grydeland at gmail.com
Wed Feb 17 05:22:17 EST 2010
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/
If you change it back, please observe that the limits on the summation
are different for the two versions.
> David
Regards,
--
Tom Grydeland
<Tom.Grydeland@(gmail.com)>
More information about the SciPy-Dev
mailing list