Help!!! Docstrings overrun by markup crap.
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. 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
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
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. Chuck
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
On Sun, Mar 21, 2010 at 3:52 AM, <josef.pktd@gmail.com> wrote:
What's a terminal ? For most packages, I'm reading sphinx generated docs.
Broadly speaking, the equivalent of cmd.exe (i.e. "dos" windows) on unix. It is important to keep a good balance between readability in un-rendered (terminals) and rendered modes (pdf, html). That's the whole point of using something like rest in the first place. cheers, David
On Sat, Mar 20, 2010 at 1:23 PM, David Cournapeau <cournape@gmail.com>wrote:
On Sun, Mar 21, 2010 at 3:52 AM, <josef.pktd@gmail.com> wrote:
What's a terminal ? For most packages, I'm reading sphinx generated
docs.
Broadly speaking, the equivalent of cmd.exe (i.e. "dos" windows) on unix. It is important to keep a good balance between readability in un-rendered (terminals) and rendered modes (pdf, html). That's the whole point of using something like rest in the first place.
And here I thought Josef was joking ;) Chuck
On 3/20/2010 2:15 PM, josef.pktd@gmail.com wrote:
As far as I know, stars are the only way to render a list in restructured txt, otherwise it looses the list formatting.
Try a definition list? Example below. Alan Returns ------- q, r if mode = 'full': - q : ndarray of float or complex, shape (M, K) - r : ndarray of float or complex, shape (K, N) K = min(M, N) r if mode = 'r': - r : ndarray of float or complex, shape (K, N) a2 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.
On Sat, Mar 20, 2010 at 1:32 PM, Alan G Isaac <aisaac@american.edu> wrote:
On 3/20/2010 2:15 PM, josef.pktd@gmail.com wrote:
As far as I know, stars are the only way to render a list in restructured txt, otherwise it looses the list formatting.
Try a definition list? Example below. Alan
Returns -------
q, r if mode = 'full': - q : ndarray of float or complex, shape (M, K) - r : ndarray of float or complex, shape (K, N)
K = min(M, N)
r if mode = 'r': - r : ndarray of float or complex, shape (K, N)
a2 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.
Maybe handle it in a manner similar to the other sections. q,r <> mode = 'r'' q: [M,N] ndarray The columns of 'q' are orthonomal. r: [K,N] ndarray Upper triangular array. ... The "<>" standing in for "if". The indentation could be moved out. Chuck
On Sun, Mar 21, 2010 at 4:18 AM, Charles R Harris <charlesr.harris@gmail.com
wrote:
On Sat, Mar 20, 2010 at 1:32 PM, Alan G Isaac <aisaac@american.edu> wrote:
On 3/20/2010 2:15 PM, josef.pktd@gmail.com wrote:
As far as I know, stars are the only way to render a list in restructured txt, otherwise it looses the list formatting.
Try a definition list? Example below. Alan
Returns -------
q, r if mode = 'full': - q : ndarray of float or complex, shape (M, K) - r : ndarray of float or complex, shape (K, N)
K = min(M, N)
r if mode = 'r': - r : ndarray of float or complex, shape (K, N)
a2 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.
Maybe handle it in a manner similar to the other sections.
q,r <> mode = 'r'' q: [M,N] ndarray The columns of 'q' are orthonomal. r: [K,N] ndarray Upper triangular array. ...
The "<>" standing in for "if". The indentation could be moved out.
Looks good, but what determines that this is a list, the <>? What if you
want a list that does not use if's? If this can be made to work, great, but it will probably be much more robust if there's some kind of markup. Stars or dashes would not look that bad imho if there would be no need for blank lines. Also, if someone feels like tackling this, please make multi-line list items work at the same time. See http://code.google.com/p/pydocweb/issues/detail?id=46 Cheers, Ralf
On Sat, Mar 20, 2010 at 7:45 PM, Ralf Gommers <ralf.gommers@googlemail.com>wrote:
On Sun, Mar 21, 2010 at 4:18 AM, Charles R Harris < charlesr.harris@gmail.com> wrote:
On Sat, Mar 20, 2010 at 1:32 PM, Alan G Isaac <aisaac@american.edu>wrote:
On 3/20/2010 2:15 PM, josef.pktd@gmail.com wrote:
As far as I know, stars are the only way to render a list in restructured txt, otherwise it looses the list formatting.
Try a definition list? Example below. Alan
Returns -------
q, r if mode = 'full': - q : ndarray of float or complex, shape (M, K) - r : ndarray of float or complex, shape (K, N)
K = min(M, N)
r if mode = 'r': - r : ndarray of float or complex, shape (K, N)
a2 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.
Maybe handle it in a manner similar to the other sections.
q,r <> mode = 'r'' q: [M,N] ndarray The columns of 'q' are orthonomal. r: [K,N] ndarray Upper triangular array. ...
The "<>" standing in for "if". The indentation could be moved out.
Looks good, but what determines that this is a list, the <>? What if you
want a list that does not use if's? If this can be made to work, great, but it will probably be much more robust if there's some kind of markup. Stars or dashes would not look that bad imho if there would be no need for blank lines.
That was just a suggestion, I think it can probably be improved upon. Thoughts?
Also, if someone feels like tackling this, please make multi-line list items work at the same time. See http://code.google.com/p/pydocweb/issues/detail?id=46
Chuck
On Sun, Mar 21, 2010 at 10:18 AM, Charles R Harris < charlesr.harris@gmail.com> wrote:
On Sat, Mar 20, 2010 at 7:45 PM, Ralf Gommers <ralf.gommers@googlemail.com
wrote:
On Sun, Mar 21, 2010 at 4:18 AM, Charles R Harris < charlesr.harris@gmail.com> wrote:
On Sat, Mar 20, 2010 at 1:32 PM, Alan G Isaac <aisaac@american.edu>wrote:
On 3/20/2010 2:15 PM, josef.pktd@gmail.com wrote:
As far as I know, stars are the only way to render a list in restructured txt, otherwise it looses the list formatting.
Try a definition list? Example below. Alan
Returns -------
q, r if mode = 'full': - q : ndarray of float or complex, shape (M, K) - r : ndarray of float or complex, shape (K, N)
K = min(M, N)
r if mode = 'r': - r : ndarray of float or complex, shape (K, N)
a2 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.
Maybe handle it in a manner similar to the other sections.
q,r <> mode = 'r'' q: [M,N] ndarray The columns of 'q' are orthonomal. r: [K,N] ndarray Upper triangular array. ...
The "<>" standing in for "if". The indentation could be moved out.
Looks good, but what determines that this is a list, the <>? What if you
want a list that does not use if's? If this can be made to work, great, but it will probably be much more robust if there's some kind of markup. Stars or dashes would not look that bad imho if there would be no need for blank lines.
That was just a suggestion, I think it can probably be improved upon. Thoughts?
In general a list should just be defined with *. Like: * item 1 * sub-item 1 Hey, a multi-line sub-item works too! * sub-item 2 * item 2 In the specific case of a variable number of return values, I do not like the if..else construction. How about this: q : ndarray The q-value. If mode='r' this contains .... If mode='economic' .... r : ndarray, optional The r-value. Is only returned if mode='r'. 'optional' could be changed to 'conditional' or something like that. Ralf
Also, if someone feels like tackling this, please make multi-line list items work at the same time. See http://code.google.com/p/pydocweb/issues/detail?id=46
Chuck
_______________________________________________ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
On Sat, Mar 20, 2010 at 10:54 PM, Ralf Gommers <ralf.gommers@googlemail.com> wrote:
On Sun, Mar 21, 2010 at 10:18 AM, Charles R Harris <charlesr.harris@gmail.com> wrote:
On Sat, Mar 20, 2010 at 7:45 PM, Ralf Gommers <ralf.gommers@googlemail.com> wrote:
On Sun, Mar 21, 2010 at 4:18 AM, Charles R Harris <charlesr.harris@gmail.com> wrote:
On Sat, Mar 20, 2010 at 1:32 PM, Alan G Isaac <aisaac@american.edu> wrote:
On 3/20/2010 2:15 PM, josef.pktd@gmail.com wrote:
As far as I know, stars are the only way to render a list in restructured txt, otherwise it looses the list formatting.
Try a definition list? Example below. Alan
Returns -------
q, r if mode = 'full': - q : ndarray of float or complex, shape (M, K) - r : ndarray of float or complex, shape (K, N)
K = min(M, N)
r if mode = 'r': - r : ndarray of float or complex, shape (K, N)
a2 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.
Maybe handle it in a manner similar to the other sections.
q,r <> mode = 'r'' q: [M,N] ndarray The columns of 'q' are orthonomal. r: [K,N] ndarray Upper triangular array. ...
The "<>" standing in for "if". The indentation could be moved out.
Looks good, but what determines that this is a list, the <>? What if you want a list that does not use if's? If this can be made to work, great, but it will probably be much more robust if there's some kind of markup. Stars or dashes would not look that bad imho if there would be no need for blank lines.
That was just a suggestion, I think it can probably be improved upon. Thoughts?
In general a list should just be defined with *. Like: * item 1 * sub-item 1 Hey, a multi-line sub-item works too! * sub-item 2 * item 2
In the specific case of a variable number of return values, I do not like the if..else construction. How about this:
q : ndarray The q-value. If mode='r' this contains .... If mode='economic' .... r : ndarray, optional The r-value. Is only returned if mode='r'.
'optional' could be changed to 'conditional' or something like that.
I agree this is better and I also thought about doing it this way. Another thought: if "terminal" refers to ipython then it should be possible that ipython removes some of the markup (stars?) when doing its magic, or not? Although that wouldn't help with a plain terminal or command shell. Josef
Ralf
Also, if someone feels like tackling this, please make multi-line list items work at the same time. See http://code.google.com/p/pydocweb/issues/detail?id=46
Chuck
_______________________________________________ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
_______________________________________________ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
On Sat, Mar 20, 2010 at 8:54 PM, Ralf Gommers <ralf.gommers@googlemail.com>wrote:
On Sun, Mar 21, 2010 at 10:18 AM, Charles R Harris < charlesr.harris@gmail.com> wrote:
On Sat, Mar 20, 2010 at 7:45 PM, Ralf Gommers < ralf.gommers@googlemail.com> wrote:
On Sun, Mar 21, 2010 at 4:18 AM, Charles R Harris < charlesr.harris@gmail.com> wrote:
On Sat, Mar 20, 2010 at 1:32 PM, Alan G Isaac <aisaac@american.edu>wrote:
On 3/20/2010 2:15 PM, josef.pktd@gmail.com wrote:
As far as I know, stars are the only way to render a list in restructured txt, otherwise it looses the list formatting.
Try a definition list? Example below. Alan
Returns -------
q, r if mode = 'full': - q : ndarray of float or complex, shape (M, K) - r : ndarray of float or complex, shape (K, N)
K = min(M, N)
r if mode = 'r': - r : ndarray of float or complex, shape (K, N)
a2 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.
Maybe handle it in a manner similar to the other sections.
q,r <> mode = 'r'' q: [M,N] ndarray The columns of 'q' are orthonomal. r: [K,N] ndarray Upper triangular array. ...
The "<>" standing in for "if". The indentation could be moved out.
Looks good, but what determines that this is a list, the <>? What if you
want a list that does not use if's? If this can be made to work, great, but it will probably be much more robust if there's some kind of markup. Stars or dashes would not look that bad imho if there would be no need for blank lines.
That was just a suggestion, I think it can probably be improved upon. Thoughts?
In general a list should just be defined with *. Like: * item 1 * sub-item 1 Hey, a multi-line sub-item works too! * sub-item 2 * item 2
I really, really want to get rid of the asterisks, they are ugly and distracting (IMHO). Unlike dashes, colons, and underlines they aren't part of the usual textual repetoire.
In the specific case of a variable number of return values, I do not like the if..else construction. How about this:
q : ndarray The q-value. If mode='r' this contains .... If mode='economic' .... r : ndarray, optional The r-value. Is only returned if mode='r'.
In the case at hand, q is optional and r has two forms.
'optional' could be changed to 'conditional' or something like that.
Chuck
On Sun, Mar 21, 2010 at 12:24 PM, Charles R Harris < charlesr.harris@gmail.com> wrote:
Maybe handle it in a manner similar to the other sections.
q,r <> mode = 'r'' q: [M,N] ndarray The columns of 'q' are orthonomal. r: [K,N] ndarray Upper triangular array. ...
The "<>" standing in for "if". The indentation could be moved out.
Looks good, but what determines that this is a list, the <>? What if
you want a list that does not use if's? If this can be made to work, great, but it will probably be much more robust if there's some kind of markup. Stars or dashes would not look that bad imho if there would be no need for blank lines.
That was just a suggestion, I think it can probably be improved upon. Thoughts?
In general a list should just be defined with *. Like: * item 1 * sub-item 1 Hey, a multi-line sub-item works too! * sub-item 2 * item 2
I really, really want to get rid of the asterisks, they are ugly and distracting (IMHO). Unlike dashes, colons, and underlines they aren't part of the usual textual repetoire.
OK, all dashes then. Those are also valid reST list specifiers.
In the specific case of a variable number of return values, I do not like the if..else construction. How about this:
q : ndarray The q-value. If mode='r' this contains .... If mode='economic' .... r : ndarray, optional The r-value. Is only returned if mode='r'.
In the case at hand, q is optional and r has two forms.
Sure, it was just an example. As long as you agree that it's better than "if mode='x' then ...", "if mode='y' then ...". Ralf
On Sun, Mar 21, 2010 at 12:24 AM, Charles R Harris <charlesr.harris@gmail.com> wrote:
On Sat, Mar 20, 2010 at 8:54 PM, Ralf Gommers <ralf.gommers@googlemail.com> wrote:
On Sun, Mar 21, 2010 at 10:18 AM, Charles R Harris <charlesr.harris@gmail.com> wrote:
On Sat, Mar 20, 2010 at 7:45 PM, Ralf Gommers <ralf.gommers@googlemail.com> wrote:
On Sun, Mar 21, 2010 at 4:18 AM, Charles R Harris <charlesr.harris@gmail.com> wrote:
On Sat, Mar 20, 2010 at 1:32 PM, Alan G Isaac <aisaac@american.edu> wrote:
On 3/20/2010 2:15 PM, josef.pktd@gmail.com wrote: > As far as I know, stars are the only way to render a list in > restructured txt, otherwise it looses the list formatting.
Try a definition list? Example below. Alan
Returns -------
q, r if mode = 'full': - q : ndarray of float or complex, shape (M, K) - r : ndarray of float or complex, shape (K, N)
K = min(M, N)
r if mode = 'r': - r : ndarray of float or complex, shape (K, N)
a2 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.
Maybe handle it in a manner similar to the other sections.
q,r <> mode = 'r'' q: [M,N] ndarray The columns of 'q' are orthonomal. r: [K,N] ndarray Upper triangular array. ...
The "<>" standing in for "if". The indentation could be moved out.
Looks good, but what determines that this is a list, the <>? What if you want a list that does not use if's? If this can be made to work, great, but it will probably be much more robust if there's some kind of markup. Stars or dashes would not look that bad imho if there would be no need for blank lines.
That was just a suggestion, I think it can probably be improved upon. Thoughts?
In general a list should just be defined with *. Like: * item 1 * sub-item 1 Hey, a multi-line sub-item works too! * sub-item 2 * item 2
I really, really want to get rid of the asterisks, they are ugly and distracting (IMHO). Unlike dashes, colons, and underlines they aren't part of the usual textual repetoire.
but bullets (bullet lists) are, at least in latex and powerpoint, and asterisks are the ASCI version of bullet points, and all my regular notes (targeted for wiki markup or rst) use them heavily to structure lists. dashes would be also ok, but I don't think rst would recognize them. My main problem with rst is that it doesn't allow hard line breaks, which forces some kind of markup to render lists. But as Ralf's rewrite shows, there is often a way to get around lists. I only know of a few places in the scipy docs, where list items in the Parameters or Returns are really necessary. Josef
In the specific case of a variable number of return values, I do not like the if..else construction. How about this:
q : ndarray The q-value. If mode='r' this contains .... If mode='economic' .... r : ndarray, optional The r-value. Is only returned if mode='r'.
In the case at hand, q is optional and r has two forms.
'optional' could be changed to 'conditional' or something like that.
Chuck
_______________________________________________ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
On Sun, Mar 21, 2010 at 12:47 PM, <josef.pktd@gmail.com> wrote:
dashes would be also ok, but I don't think rst would recognize them.
Valid list markers are *, + and - according to http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#bullet-li... My main problem with rst is that it doesn't allow hard line breaks,
Agreed, too many blank lines are needed.
Ralf
On Sun, Mar 21, 2010 at 9:51 AM, Alan G Isaac <aisaac@american.edu> wrote:
On 3/21/2010 12:54 AM, Ralf Gommers wrote:
too many blank lines are needed
Please define "need" after seeing the compact example I posted.
Personally, I think reST makes the right trade-offs, minimizing markup within the constraint of being unambiguous.
I tried http://docs.scipy.org/scipy/docs/scipy.signal.signaltools.convolve/diff/4791... last night, but no version looks really nice. I didn't manage the definition list. The mode parameter description is an example for the most common case when we need to do lists in the Parameters descriptions. But I don't think we have consistent use of markup for this case until now One alternative is here: http://docs.scipy.org/scipy/docs/scipy.interpolate.rbf.Rbf/ A good example that can be used as pattern and is acceptable would be useful. Josef
Alan Isaac _______________________________________________ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
On Sun, Mar 21, 2010 at 9:57 PM, <josef.pktd@gmail.com> wrote:
On Sun, Mar 21, 2010 at 9:51 AM, Alan G Isaac <aisaac@american.edu> wrote:
On 3/21/2010 12:54 AM, Ralf Gommers wrote:
too many blank lines are needed
Please define "need" after seeing the compact example I posted.
Personally, I think reST makes the right trade-offs, minimizing markup within the constraint of being unambiguous.
I tried
http://docs.scipy.org/scipy/docs/scipy.signal.signaltools.convolve/diff/4791...
last night, but no version looks really nice. I didn't manage the definition list.
The mode parameter description is an example for the most common case when we need to do lists in the Parameters descriptions.
But I don't think we have consistent use of markup for this case until now
One alternative is here: http://docs.scipy.org/scipy/docs/scipy.interpolate.rbf.Rbf/
A good example that can be used as pattern and is acceptable would be useful.
Both look sort of okay, but are abusing the syntax.
What do you think about the following: 1. Do not use lists with multiple indentation levels, it just doesn't look good and should not be necessary. 2. Use dashes for simple lists. 3. List with multi-line items are broken only inside the Parameters/Returns sections. This is a bug and simply needs to be fixed. (this would fix both of your examples) Cheers, Ralf
On Sun, Mar 21, 2010 at 10:16 AM, Ralf Gommers <ralf.gommers@googlemail.com> wrote:
On Sun, Mar 21, 2010 at 9:57 PM, <josef.pktd@gmail.com> wrote:
On Sun, Mar 21, 2010 at 9:51 AM, Alan G Isaac <aisaac@american.edu> wrote:
On 3/21/2010 12:54 AM, Ralf Gommers wrote:
too many blank lines are needed
Please define "need" after seeing the compact example I posted.
Personally, I think reST makes the right trade-offs, minimizing markup within the constraint of being unambiguous.
I tried
http://docs.scipy.org/scipy/docs/scipy.signal.signaltools.convolve/diff/4791...
last night, but no version looks really nice. I didn't manage the definition list.
The mode parameter description is an example for the most common case when we need to do lists in the Parameters descriptions.
But I don't think we have consistent use of markup for this case until now
One alternative is here: http://docs.scipy.org/scipy/docs/scipy.interpolate.rbf.Rbf/
A good example that can be used as pattern and is acceptable would be useful.
Both look sort of okay, but are abusing the syntax.
What do you think about the following: 1. Do not use lists with multiple indentation levels, it just doesn't look good and should not be necessary. 2. Use dashes for simple lists.
both fine with me, we can convert asterisks to dashes
3. List with multi-line items are broken only inside the Parameters/Returns sections. This is a bug and simply needs to be fixed. (this would fix both of your examples)
Does this mean if this bug gets fixed, then we wouldn't need the extra empty lines between list items? Currently, the rendering in the doc editor view for item lists has also wrong indentation http://docs.scipy.org/numpy/docs/numpy.ndarray.transpose/ but the html looks ok http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.transpose.... (correctly rendered definition lists might be nicer than bullet lists in html) Josef
Cheers, Ralf
_______________________________________________ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
On Sun, Mar 21, 2010 at 10:41 PM, <josef.pktd@gmail.com> wrote:
On Sun, Mar 21, 2010 at 10:16 AM, Ralf Gommers <ralf.gommers@googlemail.com> wrote:
Both look sort of okay, but are abusing the syntax.
What do you think about the following: 1. Do not use lists with multiple indentation levels, it just doesn't look good and should not be necessary. 2. Use dashes for simple lists.
both fine with me, we can convert asterisks to dashes
3. List with multi-line items are broken only inside the Parameters/Returns sections. This is a bug and simply needs to be fixed. (this would fix both of your examples)
Does this mean if this bug gets fixed, then we wouldn't need the extra empty lines between list items?
Yes. The following works in the Notes section, but not in Parameters: - item one - item two this is a multi-line item - item 3
Currently, the rendering in the doc editor view for item lists has also wrong indentation http://docs.scipy.org/numpy/docs/numpy.ndarray.transpose/ but the html looks ok
http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.transpose....
Html looks fine indeed. It should still look like that once that bug is fixed. Cheers, Ralf
On Sun, Mar 21, 2010 at 8:53 AM, Ralf Gommers <ralf.gommers@googlemail.com>wrote:
On Sun, Mar 21, 2010 at 10:41 PM, <josef.pktd@gmail.com> wrote:
On Sun, Mar 21, 2010 at 10:16 AM, Ralf Gommers <ralf.gommers@googlemail.com> wrote:
Both look sort of okay, but are abusing the syntax.
What do you think about the following: 1. Do not use lists with multiple indentation levels, it just doesn't look good and should not be necessary. 2. Use dashes for simple lists.
both fine with me, we can convert asterisks to dashes
3. List with multi-line items are broken only inside the Parameters/Returns sections. This is a bug and simply needs to be fixed. (this would fix both of your examples)
Does this mean if this bug gets fixed, then we wouldn't need the extra empty lines between list items?
Yes. The following works in the Notes section, but not in Parameters: - item one - item two this is a multi-line item - item 3
Currently, the rendering in the doc editor view for item lists has also wrong indentation http://docs.scipy.org/numpy/docs/numpy.ndarray.transpose/ but the html looks ok
http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.transpose....
Html looks fine indeed. It should still look like that once that bug is fixed.
Could you open a ticket for this? We need to track it somewhere. Chuck
On Mon, Mar 22, 2010 at 7:07 AM, Charles R Harris <charlesr.harris@gmail.com
wrote:
On Sun, Mar 21, 2010 at 8:53 AM, Ralf Gommers <ralf.gommers@googlemail.com
wrote:
On Sun, Mar 21, 2010 at 10:41 PM, <josef.pktd@gmail.com> wrote:
3. List with multi-line items are broken only inside the Parameters/Returns sections. This is a bug and simply needs to be fixed. (this would fix both of your examples)
Does this mean if this bug gets fixed, then we wouldn't need the extra empty lines between list items?
Yes. The following works in the Notes section, but not in Parameters: - item one - item two this is a multi-line item - item 3
Currently, the rendering in the doc editor view for item lists has also wrong indentation http://docs.scipy.org/numpy/docs/numpy.ndarray.transpose/ but the html looks ok
http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.transpose....
Html looks fine indeed. It should still look like that once that bug is fixed.
Could you open a ticket for this? We need to track it somewhere.
It's already a pydocweb ticket: http://code.google.com/p/pydocweb/issues/detail?id=46 The html in the compiled docs looks decent so I don't think it's a numpy issue. It's just hard to get markup right if the wiki doesn't work (usually the big red letters indicate actual human error). Cheers, Ralf
On Sun, Mar 21, 2010 at 9:51 PM, Alan G Isaac <aisaac@american.edu> wrote:
> On 3/21/2010 12:54 AM, Ralf Gommers wrote:
> > too many blank lines are needed
>
> Please define "need" after seeing the compact example I posted.
>
> You need 4 blank lines in your example. Now I tried adding a description
for the first argument (q) like this:
q, r if mode = 'full' :
- q : ndarray of float or complex, shape (M, K)
Description of `q`.
- r : ndarray of float or complex, shape (K, N)
That doesn't work, you need yet more blank lines (try this in the wiki
editor).
I just changed the docstring to the following, looks much better in both
plain text and html imho:
q : ndarray of float or complex, optional
The orthonormal matrix, of shape (M, K). Only returned if
``mode='full'``.
r : ndarray of float or complex, optional
The upper-triangular matrix, of shape (K, N) with K = min(M, N).
Only returned when ``mode='full'`` or ``mode='r'``.
a2 : ndarray of float or complex, optional
Array of shape (M, N), only returned when ``mode='economic``'.
The diagonal and the upper triangle of `a2` contains `r`, while
the rest of the matrix is undefined.
On Sun, Mar 21, 2010 at 9:58 PM, Ralf Gommers <ralf.gommers@googlemail.com>wrote:
On Sun, Mar 21, 2010 at 9:51 PM, Alan G Isaac <aisaac@american.edu> wrote:
On 3/21/2010 12:54 AM, Ralf Gommers wrote:
too many blank lines are needed
Please define "need" after seeing the compact example I posted.
You need 4 blank lines in your example. Now I tried adding a description for the first argument (q) like this:
q, r if mode = 'full' : - q : ndarray of float or complex, shape (M, K) Description of `q`.
- r : ndarray of float or complex, shape (K, N)
That doesn't work, you need yet more blank lines (try this in the wiki editor).
I just changed the docstring to the following, looks much better in both plain text and html imho:
q : ndarray of float or complex, optional The orthonormal matrix, of shape (M, K). Only returned if ``mode='full'``. r : ndarray of float or complex, optional The upper-triangular matrix, of shape (K, N) with K = min(M, N). Only returned when ``mode='full'`` or ``mode='r'``. a2 : ndarray of float or complex, optional Array of shape (M, N), only returned when ``mode='economic``'. The diagonal and the upper triangle of `a2` contains `r`, while the rest of the matrix is undefined.
This line in the code is fairly amusing by the way: # economic mode. Isn't actually economic. Economic mode is very similar to 'r' mode anyway, what's the point? Ralf
On Sun, Mar 21, 2010 at 8:01 AM, Ralf Gommers <ralf.gommers@googlemail.com>wrote:
On Sun, Mar 21, 2010 at 9:58 PM, Ralf Gommers <ralf.gommers@googlemail.com
wrote:
On Sun, Mar 21, 2010 at 9:51 PM, Alan G Isaac <aisaac@american.edu>wrote:
On 3/21/2010 12:54 AM, Ralf Gommers wrote:
too many blank lines are needed
Please define "need" after seeing the compact example I posted.
You need 4 blank lines in your example. Now I tried adding a description for the first argument (q) like this:
q, r if mode = 'full' : - q : ndarray of float or complex, shape (M, K) Description of `q`.
- r : ndarray of float or complex, shape (K, N)
That doesn't work, you need yet more blank lines (try this in the wiki editor).
I just changed the docstring to the following, looks much better in both plain text and html imho:
q : ndarray of float or complex, optional The orthonormal matrix, of shape (M, K). Only returned if ``mode='full'``. r : ndarray of float or complex, optional The upper-triangular matrix, of shape (K, N) with K = min(M, N). Only returned when ``mode='full'`` or ``mode='r'``. a2 : ndarray of float or complex, optional Array of shape (M, N), only returned when ``mode='economic``'. The diagonal and the upper triangle of `a2` contains `r`, while the rest of the matrix is undefined.
This line in the code is fairly amusing by the way: # economic mode. Isn't actually economic.
Economic mode is very similar to 'r' mode anyway, what's the point?
Economic mode is what the low level algorithm likely returns, it contains the info needed to contruct q if needed, or to efficiently apply q to different vectors without constructing q; constructing q adds to the computational and memory costs, as does pulling r out of the economic return. The situation is analogous to the LU decomposition where the natural form is to store both L and U in the original matrix. Other algorithms can then use that compact form to solve equations with different right hand sides. Chuck
On 3/21/2010 12:54 AM, Ralf Gommers wrote:
too many blank lines are needed
On Sun, Mar 21, 2010 at 9:51 PM, Alan G Isaac <aisaac@american.edu <mailto:aisaac@american.edu>> wrote:
Please define "need" after seeing the compact example I posted.
On 3/21/2010 9:58 AM, Ralf Gommers wrote:
You need 4 blank lines in your example. Now I tried adding a description
Here is the compact example I posted. q, r if mode = 'full': - q : ndarray of float or complex, shape (M, K) - r : ndarray of float or complex, shape (K, N) r if mode = 'r': - r : ndarray of float or complex, shape (K, N) a2 if mode = 'economic': - a2 : ndarray of float or complex, shape (M, N) K = min(M, N). The diagonal and the upper triangle of `a2` contains `r`, while the rest of `a2` is undefined. Alan
On Mon, Mar 22, 2010 at 12:27 AM, Alan G Isaac <aisaac@american.edu> wrote:
On 3/21/2010 12:54 AM, Ralf Gommers wrote:
too many blank lines are needed
On Sun, Mar 21, 2010 at 9:51 PM, Alan G Isaac <aisaac@american.edu <mailto:aisaac@american.edu>> wrote:
Please define "need" after seeing the compact example I posted.
On 3/21/2010 9:58 AM, Ralf Gommers wrote:
You need 4 blank lines in your example. Now I tried adding a description
Here is the compact example I posted.
q, r if mode = 'full': - q : ndarray of float or complex, shape (M, K) - r : ndarray of float or complex, shape (K, N) r if mode = 'r': - r : ndarray of float or complex, shape (K, N) a2 if mode = 'economic': - a2 : ndarray of float or complex, shape (M, N)
K = min(M, N). The diagonal and the upper triangle of `a2` contains `r`, while the rest of `a2` is undefined.
Looked at the wrong thing, apologies. I'll play with your example tonight.
Cheers, Ralf
On Mon, Mar 22, 2010 at 12:27 AM, Alan G Isaac <aisaac@american.edu> wrote:
On 3/21/2010 12:54 AM, Ralf Gommers wrote:
too many blank lines are needed
On Sun, Mar 21, 2010 at 9:51 PM, Alan G Isaac <aisaac@american.edu <mailto:aisaac@american.edu>> wrote:
Please define "need" after seeing the compact example I posted.
On 3/21/2010 9:58 AM, Ralf Gommers wrote:
You need 4 blank lines in your example. Now I tried adding a description
Here is the compact example I posted.
q, r if mode = 'full': - q : ndarray of float or complex, shape (M, K) - r : ndarray of float or complex, shape (K, N) r if mode = 'r': - r : ndarray of float or complex, shape (K, N) a2 if mode = 'economic': - a2 : ndarray of float or complex, shape (M, N)
K = min(M, N). The diagonal and the upper triangle of `a2` contains `r`, while the rest of `a2` is undefined.
Your example works, the only blank lines it needs is before and after the whole block, plus above "K = min(M, N)." With one level of indentation this is an alternative to dashed lists.
After adding definitions for the returned arguments I still think it doesn't look good, but that's maybe a matter of taste. Try this in the wiki (in the Notes, doesn't work in Parameters/Returns): q, r if mode = 'full': - q : ndarray of float or complex, shape (M, K) Definition of q. - r : ndarray of float or complex, shape (K, N) Definition of r. r if mode = 'r': - r : ndarray of float or complex, shape (K, N) Definition of r. a2 if mode = 'economic': - a2 : ndarray of float or complex, shape (M, N) Definition of a. K = min(M, N). The diagonal and the upper triangle of `a2` contains `r`, while the rest of `a2` is undefined. Cheers, Ralf
On 3/21/2010 12:47 AM, josef.pktd@gmail.com wrote:
dashes would be also ok, but I don't think rst would recognize them.
It does. But again, a definition list (using indentation) is also a list structure. It needs no markup besides the indentation.
My main problem with rst is that it doesn't allow hard line breaks, which forces some kind of markup to render lists.
Not true: you can use preformatted text if you want. But of course the result in not a list environment (e.g., in HTML or LatTeX output). Alan Isaac
On 3/21/2010 12:24 AM, Charles R Harris wrote:
I really, really want to get rid of the asterisks, they are ugly and distracting (IMHO).
I agree, which is why my deflist example did not use asterisks. I consider it readable and only very slightly verbose. (The blank lines are needed by reST, but the whole example is still only 14 lines long.) I also like `if` much better than `<>`, which I also find visually distracting. fwiw, Alan PS A more compact example: q, r if mode = 'full': - q : ndarray of float or complex, shape (M, K) - r : ndarray of float or complex, shape (K, N) r if mode = 'r': - r : ndarray of float or complex, shape (K, N) a2 if mode = 'economic': - a2 : ndarray of float or complex, shape (M, N) K = min(M, N). The diagonal and the upper triangle of `a2` contains `r`, while the rest of `a2` is undefined.
On Sun, Mar 21, 2010 at 2:00 AM, 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.
That's already a rule, although it could be expressed even clearer. My understanding is: latex only in the Notes section, and even there very sparingly. Ralf
On Sat, Mar 20, 2010 at 11:00 AM, 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?
Mea culpa (at least up to this point) - I'll change it back. I'm going to stay out of the whole terminal v. higher-tech display debate: I'm having trouble seeing a win-win. DG
On Sat, Mar 20, 2010 at 12:41 PM, David Goldsmith <d.l.goldsmith@gmail.com> wrote:
On Sat, Mar 20, 2010 at 11:00 AM, 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?
Mea culpa (at least up to this point) - I'll change it back.
I'm going to stay out of the whole terminal v. higher-tech display debate: I'm having trouble seeing a win-win.
DG
OK, reverted my changes, and "demoted" to "Being written" pending some form of resolution vis-a-vis the Returns list debate. DG
participants (6)
-
Alan G Isaac -
Charles R Harris -
David Cournapeau -
David Goldsmith -
josef.pktd＠gmail.com -
Ralf Gommers