[Python-ideas] Conventions for Python code documentation

[Georg Brandl]

On 01/19/2015 08: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. 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).

I'll be happy to implement that.  Basically if you use

:param x: description
:type x: type

you could just leave out the "type" line and have it generated from the annotation.

I guess it's very similar for Google and numpy style docstrings, which are
supported by the (as of 1.3 built-in) Napoleon extension.

Georg