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

[josef.pktd@gmai...]

On Sat, Mar 20, 2010 at 2:38 PM, Charles R Harris
<charlesr.harris@gmail.com> wrote:
>
>
> On Sat, Mar 20, 2010 at 12:15 PM, <josef.pktd@gmail.com> wrote:
>>
>> On Sat, Mar 20, 2010 at 2:00 PM, Charles R Harris
>> <charlesr.harris@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.

What's a terminal ?  For most packages, I'm reading sphinx generated docs.

(I know I'm an outlier compared to the "usual" users on the mailing list.)

Josef

>
> Chuck
>
>
> _______________________________________________
> NumPy-Discussion mailing list
> NumPy-Discussion@scipy.org
> http://mail.scipy.org/mailman/listinfo/numpy-discussion
>
>