[Doc-SIG] epydoc reST markup for stdlib docstrings

[Barry Warsaw]

On Apr 13, 2010, at 11:25 PM, Georg Brandl wrote:

>So far, so good, but I would *not* want to make a ":param foo:" section
>a recommendation or even mandatory.  (IMO it's too verbose, parameters can be
>explained in the text just fine.)  Valid reST is a first goal, and it should
>be achievable to slowly convert docstrings to that.

I actually find prose descriptions of parameters and return values much harder
to read.  YMMV of course.

We can definitely agree on valid reST being the top priority, as PEP 287
states.  Even this of course is not mandatory (yet).

I think it is useful to be more prescriptive, such that if folks want to
markup their parameters in other than prose, epydoc reST style is the
officially preferred format to use.  That way, we can begin to standardize the
stdlib, and build and extend tools that read that format.

>> PEP 257 does include an example for keyword arguments, but not much more is
>> said about them.  epydoc reST markup is compliant with PEP 287 IMO, by
>> adopting reST syntax.  I think Sphinx does a pretty good job of handling such
>> API markup too.
>
>Yes, I've tried to be compatible to what Epydoc supports.

Excellent.

>> A PEP might be necessary to make this a firm decision.  What do you think
>> about adopting epydoc reST markup for documenting the stdlib API?
>
>>From me, +1.
>
>(Also for this reason: Many projects pull docstrings into their Sphinx docs
>via autodoc these days, and some also document inherited APIs.  When these
>inherited APIs come from the stdlib, the markup is often confusing or not
>even valid reST.)

Yep.  I'd love to see guidelines and stronger recommendations that people can
follow so that over time, we fix this.

Thanks,
-Barry
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: not available
URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100413/7509bed6/attachment.pgp>