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

[Guido van Rossum]

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.

(*) This is too concise to my taste:
$ ls -?
ls: illegal option -- ?
usage: ls [-ABCFGHLOPRSTUWabcdefghiklmnopqrstuwx1] [file ...]
$


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