homepage

The documentation of timeit can be improved in several ways:
 * it should start with a couple of short and comprehensible examples that show the basic usage from the command-line and from the code;
 * the 3 convenience functions should be moved before the class documentation (and their order inverted);
 * the methods in the class should be reordered to show the important one first;
 * more comprehensive (but still comprehensible) examples should be added at the end;
 * sh syntax highlight should be used for the command-line usage examples;
 * the note about Python 2.3 can be removed from 3.x docs;
http://docs.python.org/dev/library/timeit.html 

+1

The sh syntax highlight can be enabled with:
.. code-block:: sh
 $ ...

Here's a patch.

I don't think there's a need for two separate examples sections (one "basic examples" and one "examples").
Also, you say a couple of times "The equivalent can be achieved from the :ref:`python-interface`", but that's not true since the command-line interface auto-calibrates, which the Python API (unfortunately) doesn't.
Besides, the results use different units and can't be directly compared.

The first example shows the basic usage and it's right at the beginning, all the other "advanced" examples are at the bottom.
About the autocalibration you are right, I'll rephrase the sentence (see also #6422).

I copy-edited the patch just looking for minor things like punctuation, etc:
+a :ref:`command-line-interface` as well as :ref:`callable <python-interface>`
a callable one
+See also Tim Peters' introduction to the "Algorithms" chapter in the Python
+Cookbook, published by O'Reilly.
italicize or underline book titles (is there a reST directive for books?)
+The following example shows how the :ref:`command-line-interface`,
no comma
+Python interface
Python Interface
+ Create a :class:`Timer` instance with the given statement, setup code and timer
+ function and run its :meth:`.timeit` method with *number* executions.
stars around setup and timer like there is with *number*?
+ Create a :class:`Timer` instance with the given statement, setup code and timer
+ function and run its :meth:`.repeat` method with the given *repeat* count and
ditto
+ Define a default timer, in a platform specific manner. On Windows,
platform-specific
+ :func:`time.clock` has microsecond granularity but :func:`time.time`'s
granularity, but
+ granularity is 1/60th of a second; on Unix, :func:`time.clock` has 1/100th of
I would just split this into two sentences since it already combines two compound sentences (i.e. it is effectively four sentences):
second. On Unix,
+ a second granularity and :func:`time.time` is much more precise. On either
granularity, and
+ Time *number* executions of the main statement. This executes the setup
statement. This
+ statement once, and then returns the time it takes to execute the main statement
+ a number of times, measured in seconds as a float. The argument is the number
*number* times
+ baseline overhead can be measured by invoking the program without arguments and
arguments, and

New changeset 60c831305e73 by Ezio Melotti in branch '2.7':
#15979: improve timeit documentation.
http://hg.python.org/cpython/rev/60c831305e73
New changeset d5a4300702c1 by Ezio Melotti in branch '3.2':
#15979: improve timeit documentation.
http://hg.python.org/cpython/rev/d5a4300702c1
New changeset ff32d390f897 by Ezio Melotti in branch '3.3':
#15979: merge with 3.2.
http://hg.python.org/cpython/rev/ff32d390f897
New changeset 85b6c1c19cb8 by Ezio Melotti in branch 'default':
#15979: merge with 3.3.
http://hg.python.org/cpython/rev/85b6c1c19cb8 

Fixed, thanks for the review!