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

[Ralf Gommers]

On Sun, Mar 21, 2010 at 10:18 AM, Charles R Harris <
charlesr.harris at gmail.com> wrote:

>
>
> On Sat, Mar 20, 2010 at 7:45 PM, Ralf Gommers <ralf.gommers at googlemail.com
> > wrote:
>
>>
>>
>> On Sun, Mar 21, 2010 at 4:18 AM, Charles R Harris <
>> charlesr.harris at gmail.com> wrote:
>>
>>>
>>>
>>> On Sat, Mar 20, 2010 at 1:32 PM, Alan G Isaac <aisaac at american.edu>wrote:
>>>
>>>> On 3/20/2010 2:15 PM, josef.pktd at 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 at scipy.org
> http://mail.scipy.org/mailman/listinfo/numpy-discussion
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20100321/353bb1c9/attachment.html>