On Wed, Apr 14, 2010 at 10:23 PM, Georg Brandl <g.bra...@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
_______________________________________________ Doc-SIG maillist - Doc-SIG@python.org http://mail.python.org/mailman/listinfo/doc-sig
