# [Numpy-discussion] Help!!! Docstrings overrun by markup crap.

Charles R Harris charlesr.harris at gmail.com
Sat Mar 20 14:38:08 EDT 2010

On Sat, Mar 20, 2010 at 12:15 PM, <josef.pktd at gmail.com> wrote:

> On Sat, Mar 20, 2010 at 2:00 PM, Charles R Harris
> <charlesr.harris at gmail.com> wrote:
> > Example,
> >
> >>     Compute the qr factorization of a matrix.
> >>
> >>     Factor the matrix a as qr, where q is orthonormal
> >>     (:math:dot( q_{:,i}, q_{:,j}) = \delta_{ij}, the Kronecker delta)
> >> and
> >>     r is upper-triangular.
> >
> > Arrggghhhh... Totally. Unreadable. Why not say the columns of q are
> > orthonormal vectors and r is upper triangular? The math tutorial should
> go
> > in the notes, if anywhere. Might mention that this is a 'thin'
> factorization
> > (Golub). Let me propose a rule: no math markup in the summary, ever.
> >
> >>     Parameters
> >>     ----------
> >>     a : array_like, shape (M, N)
> >>         Matrix to be factored.
> >>     mode : {'full', 'r', 'economic'}
> >>         Specifies the information to be returned. 'full' is the default.
> >>         mode='r' returns a "true" r, while 'economic' returns a
> >> "polluted"
> >>         r (albeit slightly faster; see Returns below).
> >>
> >
> > Oh, come now, "true", "polluted"? Sounds a bit political... Actually,
> > 'economic' contains info on the Householder reflections. In any case, why
> > mention it at all, just refer to the return documentation. And wouldn't
> > values be a better word than information?
> >
> >>
> >>     Returns
> >>     -------
> >>     * If mode = 'full':
> >>
> >>         * q : ndarray of float or complex, shape (M, K)
> >>         * r : ndarray of float or complex, shape (K, N)
> >>
> >>       Size K = min(M, N)
> >>
> >>     * If mode = 'r':
> >>
> >>       * r : ndarray of float or complex, shape (K, N)
> >>
> >>     * If mode = 'economic':
> >>
> >>       * a2 : ndarray of float or complex, shape (M, N)
> >>
> >>       The diagonal and the upper triangle of a2 contains r,
> >>       while the rest of the matrix is undefined.
> >
> > WTF? I'm seeing stars.
>
> As far as I know, stars are the only way to render a list in
> restructured txt, otherwise it looses the list formatting. I tried
> several versions, but never found a different way. (I don't remember
> whether the empty lines are strictly necessary in sphinx docs, but
> they are in rst.)
>
>
But they can't be read on a terminal. The Numpy docstring format was
designed to save vertical space, all those stars and blank lines undoes that
effort.

But, the markup creates nice hml and htmlhelp docs, and it can be
> published as pdf.
>
>
If we need that, let's fix the numpy format so we can get rid of the stars.
Personally, I think the html docs should be secondary, i.e., as long as we
are stuck with terminals, screen readability comes first.

Chuck
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20100320/273c3dc6/attachment.html>