[Python-ideas] Conventions for Python code documentation

Nathaniel Smith njs at pobox.com
Tue Jan 20 20:03:49 CET 2015

On Tue, Jan 20, 2015 at 6:39 AM, Terry Reedy <tjreedy at udel.edu> wrote:
> On 1/19/2015 2:54 PM, Guido van Rossum wrote:
>> Unfortunately PEP 257 falls short on specifying how to describe
>> arguments -- it has only one example, it's not normative, and there's
>> not much code that follows the example. The reST conventions are more
>> common, but the stdlib itself rarely uses them.
> Because I have not seen such used, except maybe once, I have been meaning to
> ask if I am allowed to use rst markup in stdlib docstrings?

If you want a standard, then the Google and/or Numpy docstring
standards are generally better than raw RST anyway: they're readable
by humans -- no-one will necessarily even notice you're using a
special format, esp. the Google standard -- and sphinx can parse them
too in case that ever becomes important.

<- then click the little arrow

Nathaniel J. Smith
Postdoctoral researcher - Informatics - University of Edinburgh

More information about the Python-ideas mailing list