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

josef.pktd@gmai... josef.pktd@gmai...
Sat Mar 20 13:15:49 CDT 2010


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, the markup creates nice hml and htmlhelp docs, and it can be
published as pdf.

Josef

>
> I may be old and crotchety, and I don't mean to be mean to the folks who
> have done the hard work to bring the docstring to its current state, but I
> think things have gotten out of hand.
>
> Chuck
>
>
>
> _______________________________________________
> NumPy-Discussion mailing list
> NumPy-Discussion@scipy.org
> http://mail.scipy.org/mailman/listinfo/numpy-discussion
>
>


More information about the NumPy-Discussion mailing list