[Python-Dev] Best practice for documentation for std lib

Eli Bendersky eliben at gmail.com
Sun Sep 22 18:37:15 CEST 2013

On Sun, Sep 22, 2013 at 8:49 AM, Barry Warsaw <barry at python.org> wrote:

> On Sep 22, 2013, at 10:34 AM, Brett Cannon wrote:
> >The rule of thumb I go by is the docstring should be enough to answer the
> >question "what args does this thing take and what does it do in general to
> >know it's the function I want and another one in the same module?" quickly
> >and succinctly; i.e. just enough so that help() reminds you about details
> >for a module you are already familiar with that might come up while at the
> >interpreter prompt. Everything else -- in-depth discussion of the
> >algorithms, extra examples, why you want to use this function, etc. -- all
> >go in the .rst docs.
> That's exactly my own rule of thumb too, so +1.

It makes a lot of sense to me too. That said, I don't see a reason why we
can't auto-generate the referenc-y stuff from docstrings into the .rst
automatically, i.e.:


Algorithms, bla bla bla, examples bla bla bla

<ref:module.py Foo.bar>  # << Auto generator pastes function signature and
docstring here

More algorithms, more bla bla, examples.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20130922/05930883/attachment.html>

More information about the Python-Dev mailing list