[Python-ideas] Conventions for Python code documentation

Guido van Rossum guido at python.org
Tue Jan 20 17:31:33 CET 2015

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.

> > It would be nice to come
>> up with a better convention that takes PEP 484 into account (so doc
>> generators can incorporate the argument type annotations into the
>> generated output, merged with per-argument from the docstring).
> My impression is that the plan is that stdlib .py files would not have
> type annotations, but that they might be in stub files.  Still true?

Correct. The stdlib is a special flower in so many ways... (Stubs are also
useful for 3rd party libraries that haven't been updated yet.)

> Would type hints be added to the signatures in .rst docs?

I think you and Georg may have to decide what to do.

--Guido van Rossum (python.org/~guido)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20150120/76949dd1/attachment.html>

More information about the Python-ideas mailing list