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

Guido van Rossum guido at python.org
Sun Sep 22 20:40:41 CEST 2013

On Sun, Sep 22, 2013 at 10:25 AM, Eli Bendersky <eliben at gmail.com> wrote:

> I think there's a general agreement in this thread that we don't intend to
> change the status quo. Both .rst docs and docstrings are important. The
> remaining question is - can we use some tool to generates parts of the
> former from the latter and thus avoid duplication and rot?

I don't think that duplication is much of an issue. Natural language
understanding is not at the level yet where you can generate a meaningful
summary from a longer text fully automatically (let alone vice versa :-) so
I think having to write both a concise docstring and a longer more detailed
description for the Doc tree is not a waste of effort at all.

As for rot, it's just as likely that rot occurs as a *result* of
autogeneration. Having to edit/patch the source code in order to improve
the documentation most likely adds an extra barrier towards improving the

--Guido van Rossum (python.org/~guido)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20130922/85f5f82b/attachment.html>

More information about the Python-Dev mailing list