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

[Ralf Gommers]

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.
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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20100321/423dcdfb/attachment.html>