Update %timeit documentation: replace best time with average time (#1…

…4141)

This PR addresses outdated documentation for the `%timeit` magic
command.

As of version 6.0.0rc1, `%timeit` measures the average time instead of
the best time.
- Related PR at the time: #9984

However, the documentation still reflects the old behavior.

### 1. Description of the `-r` option
The current documentation states the following:

https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-timeit

> -r<R>: number of repeats <R>, each consisting of <N> loops, and take
the best result. Default: 7

This seems to be the correct `average result`.

The actual code calculates the average:

https://github.com/ipython/ipython/blob/f49a797f1488a3f54a0030de12d92393f878f335/IPython/core/magics/execution.py#L112-L119

### 2. The format of the `%timeit` results in the sample code for
`%alias_magic` is outdated.

Current documentation:

https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-alias_magic
> In [2]: %t -n1 pass
> 1 loops, best of 3: 954 ns per loop

Actual result:
> 107 ns ± 43.6 ns per loop (mean ± std. dev. of 7 runs, 1 loop each)

The following pages also have outdated notation:
- Overview:
https://ipython.readthedocs.io/en/stable/overview.html#main-features-of-the-interactive-shell
- Introducing Tutorial:
https://ipython.readthedocs.io/en/stable/interactive/tutorial.html#magic-functions
- IPython reference:
https://ipython.readthedocs.io/en/stable/interactive/reference.html#magic-command-system
- Python vs IPython:
https://ipython.readthedocs.io/en/stable/interactive/python-ipython-diff.html#magics

IPython/core/magics/basic.py

@@ -109,12 +109,12 @@ def alias_magic(self, line=''):
           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 @@ def timeit(self, line='', cell=None, local_ns=None):
         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 @@ 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 @@ 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 @@ 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 @@ 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)
 
 ..