[Numpy-discussion] Help!!! Docstrings overrun by markup crap.
Sun Mar 21 09:16:45 CDT 2010
On Sun, Mar 21, 2010 at 9:57 PM, <firstname.lastname@example.org> wrote:
> On Sun, Mar 21, 2010 at 9:51 AM, Alan G Isaac <email@example.com> 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