[Python-ideas] Conventions for Python code documentation (was: PEP 484 (Type Hints) -- first draft round)

Guido van Rossum guido at python.org
Mon Jan 19 20:54:20 CET 2015


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).

On Mon, Jan 19, 2015 at 11:25 AM, Ian Cordasco <graffatcolmingov at gmail.com>
wrote:

> There's also PEP 0257 for docstring formatting.
>
> On Mon, Jan 19, 2015 at 12:51 PM, Ben Finney <ben+python at benfinney.id.au>
> wrote:
> > Cem Karan <cfkaran2 at gmail.com> writes:
> >
> >> OK, so should there be a convention for writing docstrings?
> >
> > The current convention is to use Sphinx to render a reStructuredText
> > docstring, and write the API of a class or function with
> > reStructuredText field lists.
> >
> >     <URL:http://sphinx-doc.org/domains.html#the-python-domain>
> >     <URL:http://sphinx-doc.org/domains.html#info-field-lists>
> >
> > Python's own documentation, as well as a large amount of third-party
> > packages, are written this way.
> >
> > --
> >  \        “It is seldom that liberty of any kind is lost all at once.” |
> >   `\                                                       —David Hume |
> > _o__)                                                                  |
> > Ben Finney
> >
> > _______________________________________________
> > 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/
> _______________________________________________
> 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)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20150119/9a0a2c0b/attachment-0001.html>


More information about the Python-ideas mailing list