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

https://google-styleguide.googlecode.com/svn/trunk/pyguide.html#Comments
<- then click the little arrow
https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#sections

-- 
Nathaniel J. Smith
Postdoctoral researcher - Informatics - University of Edinburgh
http://vorpus.org


More information about the Python-ideas mailing list