[Doc-SIG] epydoc reST markup for stdlib docstrings

[Georg Brandl]

Am 13.04.2010 21:12, schrieb Barry Warsaw:
> Hello Doc-Siggers,
> 
> During some recent work on the PEP 3147, I had a need to add some
> documentation (docstrings) to some new functions.  To document the function
> arguments I added epydoc reST style markup:
> 
> def ensure_bytecode_path(bytecode_path):
>     """Ensure that the __pycache__ directory for PEP 3147 pyc file exists.
> 
>     :param bytecode_path: File system path to PEP 3147 pyc file.
>     """
> 
> Now, I didn't even think twice about this because several of the larger Python
> projects I work on have already adopted epydoc reST markup for API.  During
> his review, Antoine disapproved of this, pointing to PEPs 257 and 287.  My
> reading of these PEPs however, certainly doesn't prohibit the use of epydoc
> reST markup.  Georg and I pointed to the lack of a clear, consistent convention
> in the Python stdlib.  I would like to propose that epydoc reST markup be made
> that convention.
> 
> http://epydoc.sourceforge.net/epydoc.html#epydoc-fields

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.

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

> 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.)

Georg