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

[josef.pktd at gmail.com]

On Sun, Mar 21, 2010 at 10:16 AM, Ralf Gommers
<ralf.gommers at googlemail.com> wrote:
>
>
> On Sun, Mar 21, 2010 at 9:57 PM, <josef.pktd at gmail.com> wrote:
>>
>> On Sun, Mar 21, 2010 at 9:51 AM, Alan G Isaac <aisaac at american.edu> wrote:
>> > On 3/21/2010 12:54 AM, Ralf Gommers wrote:
>> >> too many blank lines are needed
>> >
>> > Please define "need" after seeing the compact example I posted.
>> >
>> > Personally, I think reST makes the right trade-offs,
>> > minimizing markup within the constraint of being unambiguous.
>>
>> I tried
>>
>> http://docs.scipy.org/scipy/docs/scipy.signal.signaltools.convolve/diff/4791/5687/
>>
>> last night, but no version looks really nice. I didn't manage the
>> definition list.
>>
>> The mode parameter description is an example for  the most common case
>> when we need to do lists in the Parameters descriptions.
>>
>> But I don't think we have consistent use of markup for this case until now
>>
>> One alternative is here:
>> http://docs.scipy.org/scipy/docs/scipy.interpolate.rbf.Rbf/
>>
>> A good example that can be used as pattern and is acceptable would be
>> useful.
>>
> Both look sort of okay, but are abusing the syntax.
>
> What do you think about the following:
> 1. Do not use lists with multiple indentation levels, it just doesn't look
> good and should not be necessary.
> 2. Use dashes for simple lists.

both fine with me, we can convert asterisks to dashes

> 3. List with multi-line items are broken only inside the Parameters/Returns
> sections. This is a bug and simply needs to be fixed. (this would fix both
> of your examples)

Does this mean if this bug gets fixed, then we wouldn't need the extra
empty lines between list items?

Currently, the rendering in the doc editor view for item lists has
also wrong indentation
http://docs.scipy.org/numpy/docs/numpy.ndarray.transpose/
but the html looks ok
http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.transpose.html

(correctly rendered definition lists might be nicer than bullet lists in html)

Josef

>
> Cheers,
> Ralf
>
> _______________________________________________
> NumPy-Discussion mailing list
> NumPy-Discussion at scipy.org
> http://mail.scipy.org/mailman/listinfo/numpy-discussion
>
>