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

[josef.pktd at gmail.com]

On Sun, Mar 21, 2010 at 12:24 AM, Charles R Harris
<charlesr.harris at gmail.com> wrote:
>
>
> On Sat, Mar 20, 2010 at 8:54 PM, Ralf Gommers <ralf.gommers at googlemail.com>
> wrote:
>>
>>
>> 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
>>
>
> 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.

but bullets (bullet lists) are, at least in latex and powerpoint, and
asterisks are the ASCI version of bullet points, and all my regular
notes (targeted for wiki markup or rst) use them heavily to structure
lists.

dashes would be also ok, but I don't think rst would recognize them.
My main problem with rst is that it doesn't allow hard line breaks,
which forces some kind of markup to render lists.

But as Ralf's rewrite shows, there is often a way to get around lists.
I only know of a few places in the scipy docs, where list items in the
Parameters or Returns are really necessary.

Josef

>
>>
>> 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.
>
>>
>> 'optional' could be changed to 'conditional' or something like that.
>>
>
> Chuck
>
>
> _______________________________________________
> NumPy-Discussion mailing list
> NumPy-Discussion at scipy.org
> http://mail.scipy.org/mailman/listinfo/numpy-discussion
>
>