On Sun, Sep 22, 2013 at 5:31 PM, Steven D'Aprano <steve@pearwood.info> wrote:
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.

I guess preferences differ. I like reading the source, and often I find overly long docstrings distracting.

If I had the final word, I'd recommend using the current docstrings as the .rst contents and replacing the docstrings with the 1-2 line function descriptions from the PEP, e.g.:

            * median(data) -> median (middle value) of data, taking the
              average of the two middle values when there are an even
              number of values.

But omitting the signature proper, and replacing "->" with "Returns" or "Returns the". E.g.

    def median(data):
        """Returns the median (middle value) of data, taking the
           average of the two middle values when there are an even
           number of values.
        """
        ...

I'd personally also rewrite them all so that the first line of the docstring is a phrase that can stand by itself, as I describe in PEP 8, but this is used only sporadically in the stdlib.
 
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?

If it's for background information or an introduction to the theory that's fine. If it's as a substitute for proper documentation of an API I'd frown upon it. Someone in a spaceship on its way to Mars  with a copy of docs.python.org should have no problems using the library, as long as they are familiar with the basic theory such as might be explained on Wikipedia (of which the spaceship would of course also have a copy :-).

--
--Guido van Rossum (python.org/~guido)