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

Steven D'Aprano steve at pearwood.info
Mon Sep 23 02:31:42 CEST 2013


On Sun, Sep 22, 2013 at 10:07:28AM -0700, Guido van Rossum wrote:

> 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.

It is the second half that I'm not sure about. How long is *too long*
for a doc string? My own preference is to err on the side of too much 
rather than too little, since I live by help() and only fall back on the 
web documentation when I really must.

Rather than keep talking in generalities, I'll come up with a first 
draft rst document over the next week or so, put it on the tracker, and 
wait for some concrete feedback on that.

What's the policy about linking to external content from the web docs?



-- 
Steven


More information about the Python-Dev mailing list