[Doc-SIG] epydoc reST markup for stdlib docstrings

[Michael Foord]

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?:
>     >>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.
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.

Michael


>
> Cheers,
> Ralf
>
>
> _______________________________________________
> Doc-SIG maillist  -  Doc-SIG at python.org
> http://mail.python.org/mailman/listinfo/doc-sig
>    


-- 
http://www.ironpythoninaction.com/

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100414/91ccf13e/attachment-0001.html>