[Python-ideas] Conventions for Python code documentation

Devin Jeanpierre jeanpierreda at gmail.com
Mon Jan 19 23:26:12 CET 2015


On Mon, Jan 19, 2015 at 2:08 PM, Guido van Rossum <guido at python.org> wrote:
> "Napoleon"?

https://pypi.python.org/pypi/sphinxcontrib-napoleon

-- Devin

> On Mon, Jan 19, 2015 at 12:48 PM, Georg Brandl <g.brandl at gmx.net> wrote:
>>
>> 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
>>
>> _______________________________________________
>> Python-ideas mailing list
>> Python-ideas at python.org
>> https://mail.python.org/mailman/listinfo/python-ideas
>> Code of Conduct: http://python.org/psf/codeofconduct/
>
>
>
>
> --
> --Guido van Rossum (python.org/~guido)
>
> _______________________________________________
> Python-ideas mailing list
> Python-ideas at python.org
> https://mail.python.org/mailman/listinfo/python-ideas
> Code of Conduct: http://python.org/psf/codeofconduct/


More information about the Python-ideas mailing list