[Numpy-discussion] Help!!! Docstrings overrun by markup crap.
josef.pktd@gmai...
josef.pktd@gmai...
Sat Mar 20 22:59:34 CDT 2010
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
>
>
More information about the NumPy-Discussion
mailing list