On Sun, Mar 21, 2010 at 9:57 PM, <josef.pktd@gmail.com> wrote:

On Sun, Mar 21, 2010 at 9:51 AM, Alan G Isaac <aisaac@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.
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)

Cheers,
Ralf