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

[Ralf Gommers]

On Sun, Mar 21, 2010 at 12:24 PM, Charles R Harris <
charlesr.harris at 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20100321/b97b87f2/attachment.html>