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

Charles R Harris charlesr.harris@gmail....
Sat Mar 20 21:18:26 CDT 2010


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


More information about the NumPy-Discussion mailing list