classification
Title: Improve timeit documentation
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.4, Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: chris.jerdonek, docs@python, ezio.melotti, pitrou, python-dev, rhettinger
Priority: normal Keywords: patch

Created on 2012-09-20 03:26 by ezio.melotti, last changed 2012-10-02 03:06 by ezio.melotti. This issue is now closed.

Files
File name Uploaded Description Edit
issue15979.diff ezio.melotti, 2012-09-24 10:31 Patch against default
issue15979-2.diff ezio.melotti, 2012-10-02 01:04 Patch against 3.2.
Messages (9)
msg170785 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-09-20 03:26
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
msg170786 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2012-09-20 04:40
+1
msg170792 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-09-20 06:41
The sh syntax highlight can be enabled with:

.. code-block:: sh

   $ ...
msg171109 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-09-24 10:31
Here's a patch.
msg171114 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2012-09-24 10:52
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.
msg171116 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-09-24 10:57
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).
msg171767 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-10-02 01:36
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
msg171771 - (view) Author: Roundup Robot (python-dev) Date: 2012-10-02 03:02
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
msg171772 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-10-02 03:06
Fixed, thanks for the review!
History
Date User Action Args
2012-10-02 03:06:33ezio.melottisetstatus: open -> closed
versions: + Python 3.4
messages: + msg171772

resolution: fixed
stage: commit review -> resolved
2012-10-02 03:02:28python-devsetnosy: + python-dev
messages: + msg171771
2012-10-02 01:36:37chris.jerdoneksetnosy: + chris.jerdonek
messages: + msg171767
2012-10-02 01:04:08ezio.melottisetfiles: + issue15979-2.diff
stage: patch review -> commit review
2012-09-24 10:57:44ezio.melottisetmessages: + msg171116
2012-09-24 10:52:13pitrousetnosy: + pitrou
messages: + msg171114
2012-09-24 10:31:07ezio.melottisetfiles: + issue15979.diff
messages: + msg171109

assignee: docs@python -> ezio.melotti
keywords: + patch
stage: needs patch -> patch review
2012-09-20 06:41:22ezio.melottisetmessages: + msg170792
2012-09-20 04:40:41rhettingersetnosy: + rhettinger
messages: + msg170786
2012-09-20 03:26:47ezio.melotticreate