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

[Ralf Gommers]

On Mon, Mar 22, 2010 at 12:27 AM, Alan G Isaac <aisaac at 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 at american.edu
> > <mailto:aisaac at 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20100322/377d8af1/attachment.html>