[Numpy-discussion] Help!!! Docstrings overrun by markup crap.
ralf.gommers at googlemail.com
Sun Mar 21 10:16:45 EDT 2010
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
> 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:
> A good example that can be used as pattern and is acceptable would be
> 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)
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the NumPy-Discussion