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

Charles R Harris charlesr.harris@gmail....
Sat Mar 20 23:24:25 CDT 2010

```On Sat, Mar 20, 2010 at 8:54 PM, Ralf Gommers

>
>
> On Sun, Mar 21, 2010 at 10:18 AM, Charles R Harris <
> charlesr.harris@gmail.com> wrote:
>
>>
>>
>> On Sat, Mar 20, 2010 at 7:45 PM, Ralf Gommers <
>>
>>>
>>>
>>> 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?
>>
>
> 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.

> In the specific case of a variable number of return values, I do not like
>
> 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.

> 'optional' could be changed to 'conditional' or something like that.
>
>
Chuck
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/numpy-discussion/attachments/20100320/7c6c83da/attachment.html
```