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

[Westley Martínez]

Since help() is usually the first thing I use to remind myself of an
API, it's imperative that the doc strings are up to date and make sense
to end users.

So, autogeneration of doc strings would be good for someone like me who
hardly uses the html docs.

> -----Original Message-----
> From: Python-Dev [mailto:python-dev-bounces+anikom15=gmail.com at python.org] On
> Behalf Of Brett Cannon
> Sent: Sunday, September 22, 2013 7:34 AM
> To: Steven D'Aprano
> Cc: python-dev
> Subject: Re: [Python-Dev] Best practice for documentation for std lib
> 
> 
> 
> 
> On Sun, Sep 22, 2013 at 8:53 AM, Steven D'Aprano <steve at pearwood.info> wrote:
> 
> 
> 	On Sun, Sep 22, 2013 at 10:20:46AM +0200, Antoine Pitrou wrote:
> 	> On Sun, 22 Sep 2013 13:13:04 +1000
> 	> Steven D'Aprano <steve at pearwood.info> wrote:
> 	> > Hi all,
> 	> >
> 	> > I have a question about how I should manage documentation for the
> 	> > statistics module for Python 3.4. At the moment, I have extensive
> 	> > docstrings in the module itself. I don't believe anyone has flagged
> that
> 	> > as "too much information" in a code review, so I'm going to assume
> that
> 	> > large docstrings will be acceptable.
> 	>
> 	> Related question: do the extensive docstrings make "help(stats)"
> 	> painful to browse through?
> 
> 
> 	Not to me. I can page through help(statistics) with 18 presses of the
> 	space bar, versus 20 for random or 45 for unittest. (29 lines per page.)
> 
> 	Admittedly statistics has fewer functions/classes than random, but I
> 	find that fewer, larger pieces of documentation are easier to read than
> 	lots of tiny one-line mentions that don't actually tell you anything.
> 	E.g. from unittest:
> 
> 	     |  Methods defined here:
> 	     |
> 	     |  __init__(self, stream, descriptions, verbosity)
> 	     |
> 	     |  addError(self, test, err)
> 	     |
> 	     |  addExpectedFailure(self, test, err)
> 	     |
> 	     |  addFailure(self, test, err)
> 	     |
> 	     |  addSkip(self, test, reason)
> 
> 	and so on for nearly a page. unittest is also packed with many, many
> 	one-line methods listed as deprecated.
> 
> 	I admit I'm a bit of a stats and maths junkie, I read stats text books
> 	for fun. So perhaps I'm not the best person to judge how much
> 	information is too much information. Comments to the tracker please:
> 
> 	http://bugs.python.org/issue18606
> 
> 
> The rule of thumb I go by is the docstring should be enough to answer the
> question "what args does this thing take and what does it do in general to
> know it's the function I want and another one in the same module?" quickly and
> succinctly; i.e. just enough so that help() reminds you about details for a
> module you are already familiar with that might come up while at the
> interpreter prompt. Everything else -- in-depth discussion of the algorithms,
> extra examples, why you want to use this function, etc. -- all go in the .rst
> docs.