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

[Stephen J. Turnbull]

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.