[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