[Doc-SIG] epydoc reST markup for stdlib docstrings

[Ralf Gommers]

On Wed, Apr 14, 2010 at 10:23 PM, Georg Brandl <g.brandl at gmx.net> wrote:

> Am 14.04.2010 14:07, schrieb Barry Warsaw:
> > On Apr 14, 2010, at 11:58 PM, Nick Coghlan wrote:
> >
> >>Barry Warsaw wrote:
> >>> On Apr 14, 2010, at 01:30 AM, Michael Foord wrote:
> >>>
> >>>> Definite +1 from me on adopting reST in docstrings as a standard. I
> >>>> haven't looked at the Epydoc convention for parameters (etc) well
> enough
> >>>> to have an opinion on that.
> >>>
> >>> The thing I like about them is that the rules are very simple, and once
> >>> learned are easy to remember.
> >>
> >>Did you look at the NumPy guidelines Ralf posted?:
> >>http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
> >>
> >>Those look very clean to me, and fairly similar to what we already do in
> >>the ReST docs.
> >>
> >>Because epydoc works with tags rather than sections, it looks a lot
> >>"noisier" to me when reading the plain text version.
> >
> > And I'm not keen on the sections since I think they consume too much
> vertical
> > whitespace.  And I like the tags of epydoc format on the left side for
> their
> > regularity.
>
> Also, the numpy docstring conventions also aren't valid reST and therefore
> need preprocessing.  (Making them reST isn't hard but requires even more
> vertical space.)
>
> The preprocessing should not be an issue, especially since the code for
that already exists and is heavily used.

The vertical whitespace vs tags is a taste issue, I agree, from a developer
perspective. From a user perspective however, the numpy standard is clearly
more readable in a terminal. That's why it looks the way it does. And
reading docstrings in a terminal is not a fringe use case by the way.

Cheers,
Ralf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100414/6555ed87/attachment.html>