[Python-ideas] Conventions for Python code documentation

Todd toddrjen at gmail.com
Tue Jan 20 19:38:16 CET 2015

On Jan 20, 2015 5:32 PM, "Guido van Rossum" <guido at python.org> wrote:
> On Mon, Jan 19, 2015 at 10:39 PM, 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?
> I prefer you don't use them. We don't generate docs from the stdlib
sources, and if someone generated them locally they would probably be doing
themselves a disservice -- the docstrings exist for the benefit of the
help() builtin, which AFAIK doesn't understand rst markup.

Might the lack of rst support in help() be something to address either as
part of this effort or in parallel with it?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20150120/3b30e368/attachment.html>

More information about the Python-ideas mailing list