[Python-ideas] Conventions for Python code documentation

[Guido van Rossum]

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>