[Doc-SIG] epydoc reST markup for stdlib docstrings
fuzzyman at voidspace.org.uk
Wed Apr 14 17:37:28 CEST 2010
On 14/04/2010 16:07, Barry Warsaw wrote:
> 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. Everyone's got a different opinion, and the only one that matters
> is the BDFL's. :)
Well, perhaps move this discussion to python-dev with the intent of
creating a PEP and asking for BDFL pronouncement? The two contenders
seem to be numpy format and epydoc format. We seem to have a consensus
that adopting a standard for the standard library is a good idea.
Once we have settled on a basic format we can thrash out all the
specifics in the PEP.
All the best,
> OTOH, the specifics don't matter as much as just picking one for the stdlib.
More information about the Doc-SIG