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

[josef.pktd@gmai...]

On Sat, Mar 20, 2010 at 10:54 PM, Ralf Gommers
<ralf.gommers@googlemail.com> wrote:
>
>
> 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
>> <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?
>
> 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.

I agree this is better and I also thought about doing it this way.

Another thought: if "terminal" refers to ipython then it should be
possible that ipython removes some of the markup (stars?) when doing
its magic, or not?
Although that wouldn't help with a plain terminal or command shell.

Josef


>
> 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@scipy.org
>> http://mail.scipy.org/mailman/listinfo/numpy-discussion
>>
>
>
> _______________________________________________
> NumPy-Discussion mailing list
> NumPy-Discussion@scipy.org
> http://mail.scipy.org/mailman/listinfo/numpy-discussion
>
>