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

Ralf Gommers ralf.gommers@googlemail....
Sat Mar 20 20:45:38 CDT 2010


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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/numpy-discussion/attachments/20100321/0094b774/attachment.html 


More information about the NumPy-Discussion mailing list