<br><br><div class="gmail_quote">On Sat, Mar 20, 2010 at 12:15 PM,  <span dir="ltr"><<a href="mailto:josef.pktd@gmail.com">josef.pktd@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
<div><div></div><div class="h5">On Sat, Mar 20, 2010 at 2:00 PM, Charles R Harris<br>
<<a href="mailto:charlesr.harris@gmail.com">charlesr.harris@gmail.com</a>> wrote:<br>
> Example,<br>
><br>
>>     Compute the qr factorization of a matrix.<br>
>><br>
>>     Factor the matrix `a` as `qr`, where `q` is orthonormal<br>
>>     (:math:`dot( q_{:,i}, q_{:,j}) = \delta_{ij}`, the Kronecker delta)<br>
>> and<br>
>>     `r` is upper-triangular.<br>
><br>
> Arrggghhhh... Totally. Unreadable. Why not say the columns of q are<br>
> orthonormal vectors and r is upper triangular? The math tutorial should go<br>
> in the notes, if anywhere. Might mention that this is a 'thin' factorization<br>
> (Golub). Let me propose a rule: no math markup in the summary, ever.<br>
><br>
>>     Parameters<br>
>>     ----------<br>
>>     a : array_like, shape (M, N)<br>
>>         Matrix to be factored.<br>
>>     mode : {'full', 'r', 'economic'}<br>
>>         Specifies the information to be returned. 'full' is the default.<br>
>>         mode='r' returns a "true" `r`, while 'economic' returns a<br>
>> "polluted"<br>
>>         `r` (albeit slightly faster; see Returns below).<br>
>><br>
><br>
> Oh, come now, "true", "polluted"? Sounds a bit political... Actually,<br>
> 'economic' contains info on the Householder reflections. In any case, why<br>
> mention it at all, just refer to the return documentation. And wouldn't<br>
> values be a better word than information?<br>
><br>
>><br>
>>     Returns<br>
>>     -------<br>
>>     * If mode = 'full':<br>
>><br>
>>         * q : ndarray of float or complex, shape (M, K)<br>
>>         * r : ndarray of float or complex, shape (K, N)<br>
>><br>
>>       Size K = min(M, N)<br>
>><br>
>>     * If mode = 'r':<br>
>><br>
>>       * r : ndarray of float or complex, shape (K, N)<br>
>><br>
>>     * If mode = 'economic':<br>
>><br>
>>       * a2 : ndarray of float or complex, shape (M, N)<br>
>><br>
>>       The diagonal and the upper triangle of a2 contains r,<br>
>>       while the rest of the matrix is undefined.<br>
><br>
> WTF? I'm seeing stars.<br>
<br>
</div></div>As far as I know, stars are the only way to render a list in<br>
restructured txt, otherwise it looses the list formatting. I tried<br>
several versions, but never found a different way. (I don't remember<br>
whether the empty lines are strictly necessary in sphinx docs, but<br>
they are in rst.)<br>
<br></blockquote><div> </div><div>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. <br><br></div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
But, the markup creates nice hml and htmlhelp docs, and it can be<br>
published as pdf.<br>
<br></blockquote><div><br>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.<br>
<br>Chuck<br></div><br></div>