[Numpy-discussion] Help!!! Docstrings overrun by markup crap.
josef.pktd@gmai...
josef.pktd@gmai...
Sat Mar 20 13:52:35 CDT 2010
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
>
>
More information about the NumPy-Discussion
mailing list