[Doc-SIG] epydoc reST markup for stdlib docstrings
fuzzyman at voidspace.org.uk
Wed Apr 14 16:56:45 CEST 2010
On 14/04/2010 16:48, Ralf Gommers wrote:
> On Wed, Apr 14, 2010 at 10:23 PM, Georg Brandl <g.brandl at gmx.net
> <mailto: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?:
> >>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
> 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.
I would say that reading docstrings in a terminal is the *main* use case
- but that is why I tend to value the vertical space highly and
personally prefer the less verbose way.
> Doc-SIG maillist - Doc-SIG at python.org
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Doc-SIG