Update timeit documentation: replace best time with average time

IPython/core/magics/basic.py

@@ -109,12 +109,12 b' class BasicMagics(Magics):'
           Created `%%t` as an alias for `%%timeit`.
 
           In [2]: %t -n1 pass
-          1 loops, best of 3: 954 ns per loop
+          107 ns ± 43.6 ns per loop (mean ± std. dev. of 7 runs, 1 loop each)
 
           In [3]: %%t -n1
              ...: pass
              ...:
-          1 loops, best of 3: 954 ns per loop
+          107 ns ± 58.3 ns per loop (mean ± std. dev. of 7 runs, 1 loop each)
 
           In [4]: %alias_magic --cell whereami pwd
           UsageError: Cell magic function `%%pwd` not found.

IPython/core/magics/execution.py

@@ -1050,7 +1050,7 b' class ExecutionMagics(Magics):'
         provided, <N> is determined so as to get sufficient accuracy.
 
         -r<R>: number of repeats <R>, each consisting of <N> loops, and take the
-        best result.
+        average result.
         Default: 7
 
         -t: use time.time to measure the time, which is the default on Unix.

docs/source/interactive/python-ipython-diff.rst

@@ -218,10 +218,10 b' Magics support assignment:'
 .. code-block:: ipython
 
     In [1]: results = %timeit -r1 -n1 -o list(range(1000))
-    1 loops, best of 1: 21.1 µs per loop
+    62.1 µs ± 0 ns per loop (mean ± std. dev. of 1 run, 1 loop each)
 
     In [2]: results
-    Out[2]: <TimeitResult : 1 loops, best of 1: 21.1 µs per loop>
+    <TimeitResult : 62.1 µs ± 0 ns per loop (mean ± std. dev. of 1 run, 1 loop each)>
 
 Magics with double percent signs (``%%``) can spread over multiple lines, but they do not support assignments:
 

docs/source/interactive/reference.rst

@@ -117,7 +117,7 b' The following uses the builtin :magic:`timeit` in cell mode::'
       ...: min(x)
       ...: max(x)
       ...:
-  1000 loops, best of 3: 438 us per loop
+  518 µs ± 4.39 µs per loop (mean ± std. dev. of 7 runs, 1000 loops each)
 
 In this case, ``x = range(10000)`` is called as the line argument, and the
 block with ``min(x)`` and ``max(x)`` is called as the cell body.  The

docs/source/interactive/tutorial.rst

@@ -133,12 +133,12 b' The following examples show how to call the built-in :magic:`timeit` magic, both'
 in line and cell mode::
 
       In [1]: %timeit range(1000)
-      100000 loops, best of 3: 7.76 us per loop
+      179 ns ± 2.66 ns per loop (mean ± std. dev. of 7 runs, 10000000 loops each)
 
       In [2]: %%timeit x = range(10000)
       ...: max(x)
       ...: 
-      1000 loops, best of 3: 223 us per loop
+      264 µs ± 1 µs per loop (mean ± std. dev. of 7 runs, 1000 loops each)
 
 The built-in magics include:
 

docs/source/overview.rst

@@ -172,10 +172,10 b' Main features of the interactive shell'
 .. sourcecode:: ipython
 
     In [1]: %timeit 1+1
-    10000000 loops, best of 3: 25.5 ns per loop
+    7.88 ns ± 0.0494 ns per loop (mean ± std. dev. of 7 runs, 100000000 loops each)
 
     In [2]: %timeit [math.sin(x) for x in range(5000)]
-    1000 loops, best of 3: 719 µs per loop
+    608 µs ± 5.57 µs per loop (mean ± std. dev. of 7 runs, 1000 loops each)
 
 ..