On Sat, Mar 20, 2010 at 2:38 PM, Charles R Harris <[email protected]> wrote: > > > On Sat, Mar 20, 2010 at 12:15 PM, <[email protected]> wrote: >> >> On Sat, Mar 20, 2010 at 2:00 PM, Charles R Harris >> <[email protected]> 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 > [email protected] > http://mail.scipy.org/mailman/listinfo/numpy-discussion > > _______________________________________________ NumPy-Discussion mailing list [email protected] http://mail.scipy.org/mailman/listinfo/numpy-discussion
