[Doc-SIG] epydoc reST markup for stdlib docstrings

[Michael Foord]

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

Michael
> OTOH, the specifics don't matter as much as just picking one for the stdlib.
>
> -Barry
>
>    


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