[Python-Dev] Best practice for documentation for std lib (original) (raw)

Eli Bendersky eliben at gmail.com
Sun Sep 22 19:25:08 CEST 2013

On Sun, Sep 22, 2013 at 10:07 AM, Guido van Rossum <guido at python.org> wrote:

On Sun, Sep 22, 2013 at 9:53 AM, Stephen J. Turnbull <stephen at xemacs.org>wrote:

Eli Bendersky writes:

> IMHO the right way to think about it is that the .rst files are by > far the more important documentation. Sometimes we forget that > most Python programmers are people who won't go into the source Why "source"? The whole point of docstrings is that they are not comments found only in the source, but available at run time. In fact, programmers who also use environments like Lisp or R (not to forget Idle) will reach for "help(mean)", and that works fine for Steven, because he provides such nice docstrings. Some people prefer to write separate manuals, and some modules should be documented that way because their internal complexity or whatever. That's true, but I would hope authors who prefer "literate programming" (or the poor man's lit prog that is writing only docstrings) are encouraged to do so when appropriate. Of course, like any other contribution, since that style is not currently supported by python-dev, they'd be asked to step up and support it themselves -- if a user reports the docs won't build, they need to address that like they would a build bug in the code. Authors writing 3rd party packages can do what they want. But for the stdlib it's been settled for ages: docstrings should be concise (but not cryptic(*)), longer documentation go into the separately written text for docs.python.org.

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?

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

More information about the Python-Dev mailing list