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

[Guido van Rossum]

On Sun, Sep 22, 2013 at 5:31 PM, Steven D'Aprano <steve at 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)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20130922/79218312/attachment.html>