Merge pull request #17976 from rnarkk/format-quickstart

DOC: Add/remove spaces in snippets and re-format here and there

1 files changed, 181 insertions, 197 deletions

diff --git a/doc/source/user/quickstart.rst b/doc/source/user/quickstart.rst
index 8fdc6ec36..8719e6eef 100644
--- a/doc/source/user/quickstart.rst
+++ b/doc/source/user/quickstart.rst
@@ -53,8 +53,8 @@ axis has a length of 2, the second axis has a length of 3.
 
 ::
 
-    [[ 1., 0., 0.],
-     [ 0., 1., 2.]]
+    [[1., 0., 0.],
+     [0., 1., 2.]]
 
 NumPy's array class is called ``ndarray``. It is also known by the alias
 ``array``. Note that ``numpy.array`` is not the same as the Standard
@@ -128,7 +128,7 @@ from the type of the elements in the sequences.
 ::
 
     >>> import numpy as np
-    >>> a = np.array([2,3,4])
+    >>> a = np.array([2, 3, 4])
     >>> a
     array([2, 3, 4])
     >>> a.dtype
@@ -142,11 +142,11 @@ rather than providing a single sequence as an argument.
 
 ::
 
-    >>> a = np.array(1,2,3,4)    # WRONG
+    >>> a = np.array(1, 2, 3, 4)    # WRONG
     Traceback (most recent call last):
       ...
     TypeError: array() takes from 1 to 2 positional arguments but 4 were given
-    >>> a = np.array([1,2,3,4])  # RIGHT
+    >>> a = np.array([1, 2, 3, 4])  # RIGHT
 
 ``array`` transforms sequences of sequences into two-dimensional arrays,
 sequences of sequences of sequences into three-dimensional arrays, and
@@ -154,7 +154,7 @@ so on.
 
 ::
 
-    >>> b = np.array([(1.5,2,3), (4,5,6)])
+    >>> b = np.array([(1.5, 2, 3), (4, 5, 6)])
     >>> b
     array([[1.5, 2. , 3. ],
            [4. , 5. , 6. ]])
@@ -163,7 +163,7 @@ The type of the array can also be explicitly specified at creation time:
 
 ::
 
-    >>> c = np.array( [ [1,2], [3,4] ], dtype=complex )
+    >>> c = np.array([[1, 2], [3, 4]], dtype=complex)
     >>> c
     array([[1.+0.j, 2.+0.j],
            [3.+0.j, 4.+0.j]])
@@ -185,7 +185,7 @@ state of the memory. By default, the dtype of the created array is
     array([[0., 0., 0., 0.],
            [0., 0., 0., 0.],
            [0., 0., 0., 0.]])
-    >>> np.ones( (2,3,4), dtype=np.int16 )                # dtype can also be specified
+    >>> np.ones((2, 3, 4), dtype=np.int16)  # dtype can also be specified
     array([[[1, 1, 1, 1],
             [1, 1, 1, 1],
             [1, 1, 1, 1]],
@@ -193,9 +193,9 @@ state of the memory. By default, the dtype of the created array is
            [[1, 1, 1, 1],
             [1, 1, 1, 1],
             [1, 1, 1, 1]]], dtype=int16)
-    >>> np.empty( (2,3) )                                 # uninitialized
-    array([[  3.73603959e-262,   6.02658058e-154,   6.55490914e-260],  # may vary
-           [  5.30498948e-313,   3.14673309e-307,   1.00000000e+000]])
+    >>> np.empty((2, 3))  # uninitialized, the result may vary
+    array([[3.73603959e-262, 6.02658058e-154, 6.55490914e-260],
+           [5.30498948e-313, 3.14673309e-307, 1.00000000e+000]])
 
 To create sequences of numbers, NumPy provides the ``arange`` function
 which is analogous to the Python built-in ``range``, but returns an
@@ -203,9 +203,9 @@ array.
 
 ::
 
-    >>> np.arange( 10, 30, 5 )
+    >>> np.arange(10, 30, 5)
     array([10, 15, 20, 25])
-    >>> np.arange( 0, 2, 0.3 )                 # it accepts float arguments
+    >>> np.arange(0, 2, 0.3)  # it accepts float arguments
     array([0. , 0.3, 0.6, 0.9, 1.2, 1.5, 1.8])
 
 When ``arange`` is used with floating point arguments, it is generally
@@ -215,9 +215,9 @@ to use the function ``linspace`` that receives as an argument the number
 of elements that we want, instead of the step::
 
     >>> from numpy import pi
-    >>> np.linspace( 0, 2, 9 )                 # 9 numbers from 0 to 2
+    >>> np.linspace(0, 2, 9)                   # 9 numbers from 0 to 2
     array([0.  , 0.25, 0.5 , 0.75, 1.  , 1.25, 1.5 , 1.75, 2.  ])
-    >>> x = np.linspace( 0, 2*pi, 100 )        # useful to evaluate function at lots of points
+    >>> x = np.linspace(0, 2 * pi, 100)        # useful to evaluate function at lots of points
     >>> f = np.sin(x)
 
 .. seealso::
@@ -251,18 +251,18 @@ matrices and tridimensionals as lists of matrices.
 
 ::
 
-    >>> a = np.arange(6)                         # 1d array
+    >>> a = np.arange(6)                    # 1d array
     >>> print(a)
     [0 1 2 3 4 5]
-    >>>
-    >>> b = np.arange(12).reshape(4,3)           # 2d array
+    >>> 
+    >>> b = np.arange(12).reshape(4, 3)     # 2d array
     >>> print(b)
     [[ 0  1  2]
      [ 3  4  5]
      [ 6  7  8]
      [ 9 10 11]]
-    >>>
-    >>> c = np.arange(24).reshape(2,3,4)         # 3d array
+    >>> 
+    >>> c = np.arange(24).reshape(2, 3, 4)  # 3d array
     >>> print(c)
     [[[ 0  1  2  3]
       [ 4  5  6  7]
@@ -280,8 +280,8 @@ central part of the array and only prints the corners::
 
     >>> print(np.arange(10000))
     [   0    1    2 ... 9997 9998 9999]
-    >>>
-    >>> print(np.arange(10000).reshape(100,100))
+    >>> 
+    >>> print(np.arange(10000).reshape(100, 100))
     [[   0    1    2 ...   97   98   99]
      [ 100  101  102 ...  197  198  199]
      [ 200  201  202 ...  297  298  299]
@@ -295,7 +295,7 @@ can change the printing options using ``set_printoptions``.
 
 ::
 
-    >>> np.set_printoptions(threshold=sys.maxsize)       # sys module should be imported
+    >>> np.set_printoptions(threshold=sys.maxsize)  # sys module should be imported
 
 
 .. _quickstart.basic-operations:
@@ -308,35 +308,35 @@ created and filled with the result.
 
 ::
 
-    >>> a = np.array( [20,30,40,50] )
-    >>> b = np.arange( 4 )
+    >>> a = np.array([20, 30, 40, 50])
+    >>> b = np.arange(4)
     >>> b
     array([0, 1, 2, 3])
-    >>> c = a-b
+    >>> c = a - b
     >>> c
     array([20, 29, 38, 47])
     >>> b**2
     array([0, 1, 4, 9])
-    >>> 10*np.sin(a)
+    >>> 10 * np.sin(a)
     array([ 9.12945251, -9.88031624,  7.4511316 , -2.62374854])
-    >>> a<35
+    >>> a < 35
     array([ True,  True, False, False])
 
 Unlike in many matrix languages, the product operator ``*`` operates
 elementwise in NumPy arrays. The matrix product can be performed using
 the ``@`` operator (in python >=3.5) or the ``dot`` function or method::
 
-    >>> A = np.array( [[1,1],
-    ...                [0,1]] )
-    >>> B = np.array( [[2,0],
-    ...                [3,4]] )
-    >>> A * B                       # elementwise product
+    >>> A = np.array([[1, 1],
+    ...               [0, 1]])
+    >>> B = np.array([[2, 0],
+    ...               [3, 4]])
+    >>> A * B     # elementwise product
     array([[2, 0],
            [0, 4]])
-    >>> A @ B                       # matrix product
+    >>> A @ B     # matrix product
     array([[5, 4],
            [3, 4]])
-    >>> A.dot(B)                    # another matrix product
+    >>> A.dot(B)  # another matrix product
     array([[5, 4],
            [3, 4]])
 
@@ -345,9 +345,9 @@ existing array rather than create a new one.
 
 ::
 
-    >>> rg = np.random.default_rng(1)     # create instance of default random number generator
-    >>> a = np.ones((2,3), dtype=int)
-    >>> b = rg.random((2,3))
+    >>> rg = np.random.default_rng(1)  # create instance of default random number generator
+    >>> a = np.ones((2, 3), dtype=int)
+    >>> b = rg.random((2, 3))
     >>> a *= 3
     >>> a
     array([[3, 3, 3],
@@ -356,7 +356,7 @@ existing array rather than create a new one.
     >>> b
     array([[3.51182162, 3.9504637 , 3.14415961],
            [3.94864945, 3.31183145, 3.42332645]])
-    >>> a += b                            # b is not automatically converted to integer type
+    >>> a += b  # b is not automatically converted to integer type
     Traceback (most recent call last):
         ...
     numpy.core._exceptions._UFuncOutputCastingError: Cannot cast ufunc 'add' output from dtype('float64') to dtype('int64') with casting rule 'same_kind'
@@ -368,15 +368,15 @@ as upcasting).
 ::
 
     >>> a = np.ones(3, dtype=np.int32)
-    >>> b = np.linspace(0,pi,3)
+    >>> b = np.linspace(0, pi, 3)
     >>> b.dtype.name
     'float64'
-    >>> c = a+b
+    >>> c = a + b
     >>> c
     array([1.        , 2.57079633, 4.14159265])
     >>> c.dtype.name
     'float64'
-    >>> d = np.exp(c*1j)
+    >>> d = np.exp(c * 1j)
     >>> d
     array([ 0.54030231+0.84147098j, -0.84147098+0.54030231j,
            -0.54030231-0.84147098j])
@@ -388,7 +388,7 @@ the array, are implemented as methods of the ``ndarray`` class.
 
 ::
 
-    >>> a = rg.random((2,3))
+    >>> a = rg.random((2, 3))
     >>> a
     array([[0.82770259, 0.40919914, 0.54959369],
            [0.02755911, 0.75351311, 0.53814331]])
@@ -404,19 +404,19 @@ of numbers, regardless of its shape. However, by specifying the ``axis``
 parameter you can apply an operation along the specified axis of an
 array::
 
-    >>> b = np.arange(12).reshape(3,4)
+    >>> b = np.arange(12).reshape(3, 4)
     >>> b
     array([[ 0,  1,  2,  3],
            [ 4,  5,  6,  7],
            [ 8,  9, 10, 11]])
     >>>
-    >>> b.sum(axis=0)                            # sum of each column
+    >>> b.sum(axis=0)     # sum of each column
     array([12, 15, 18, 21])
     >>>
-    >>> b.min(axis=1)                            # min of each row
+    >>> b.min(axis=1)     # min of each row
     array([0, 4, 8])
     >>>
-    >>> b.cumsum(axis=1)                         # cumulative sum along each row
+    >>> b.cumsum(axis=1)  # cumulative sum along each row
     array([[ 0,  1,  3,  6],
            [ 4,  9, 15, 22],
            [ 8, 17, 27, 38]])
@@ -427,7 +427,7 @@ Universal Functions
 
 NumPy provides familiar mathematical functions such as sin, cos, and
 exp. In NumPy, these are called "universal
-functions"(\ ``ufunc``). Within NumPy, these functions
+functions" (\ ``ufunc``). Within NumPy, these functions
 operate elementwise on an array, producing an array as output.
 
 ::
@@ -507,15 +507,15 @@ and other Python sequences.
     8
     >>> a[2:5]
     array([ 8, 27, 64])
-    # equivalent to a[0:6:2] = 1000;
-    # from start to position 6, exclusive, set every 2nd element to 1000
+    >>> # equivalent to a[0:6:2] = 1000;
+    >>> # from start to position 6, exclusive, set every 2nd element to 1000
     >>> a[:6:2] = 1000
     >>> a
     array([1000,    1, 1000,   27, 1000,  125,  216,  343,  512,  729])
-    >>> a[ : :-1]                                 # reversed a
+    >>> a[::-1]  # reversed a
     array([ 729,  512,  343,  216,  125, 1000,   27, 1000,    1, 1000])
     >>> for i in a:
-    ...     print(i**(1/3.))
+    ...     print(i**(1 / 3.))
     ...
     9.999999999999998
     1.0
@@ -532,23 +532,23 @@ and other Python sequences.
 **Multidimensional** arrays can have one index per axis. These indices
 are given in a tuple separated by commas::
 
-    >>> def f(x,y):
-    ...     return 10*x+y
+    >>> def f(x, y):
+    ...     return 10 * x + y
     ...
-    >>> b = np.fromfunction(f,(5,4),dtype=int)
+    >>> b = np.fromfunction(f, (5, 4), dtype=int)
     >>> b
     array([[ 0,  1,  2,  3],
            [10, 11, 12, 13],
            [20, 21, 22, 23],
            [30, 31, 32, 33],
            [40, 41, 42, 43]])
-    >>> b[2,3]
+    >>> b[2, 3]
     23
-    >>> b[0:5, 1]                       # each row in the second column of b
+    >>> b[0:5, 1]  # each row in the second column of b
     array([ 1, 11, 21, 31, 41])
-    >>> b[ : ,1]                        # equivalent to the previous example
+    >>> b[:, 1]    # equivalent to the previous example
     array([ 1, 11, 21, 31, 41])
-    >>> b[1:3, : ]                      # each column in the second and third row of b
+    >>> b[1:3, :]  # each column in the second and third row of b
     array([[10, 11, 12, 13],
            [20, 21, 22, 23]])
 
@@ -557,34 +557,34 @@ indices are considered complete slices\ ``:``
 
 ::
 
-    >>> b[-1]                                  # the last row. Equivalent to b[-1,:]
+    >>> b[-1]   # the last row. Equivalent to b[-1, :]
     array([40, 41, 42, 43])
 
 The expression within brackets in ``b[i]`` is treated as an ``i``
 followed by as many instances of ``:`` as needed to represent the
 remaining axes. NumPy also allows you to write this using dots as
-``b[i,...]``.
+``b[i, ...]``.
 
 The **dots** (``...``) represent as many colons as needed to produce a
 complete indexing tuple. For example, if ``x`` is an array with 5
 axes, then
 
--  ``x[1,2,...]`` is equivalent to ``x[1,2,:,:,:]``,
--  ``x[...,3]`` to ``x[:,:,:,:,3]`` and
--  ``x[4,...,5,:]`` to ``x[4,:,:,5,:]``.
+-  ``x[1, 2, ...]`` is equivalent to ``x[1, 2, :, :, :]``,
+-  ``x[..., 3]`` to ``x[:, :, :, :, 3]`` and
+-  ``x[4, ..., 5, :]`` to ``x[4, :, :, 5, :]``.
 
 ::
 
-    >>> c = np.array( [[[  0,  1,  2],               # a 3D array (two stacked 2D arrays)
-    ...                 [ 10, 12, 13]],
-    ...                [[100,101,102],
-    ...                 [110,112,113]]])
+    >>> c = np.array([[[  0,  1,  2],  # a 3D array (two stacked 2D arrays)
+    ...                [ 10, 12, 13]],
+    ...               [[100, 101, 102],
+    ...                [110, 112, 113]]])
     >>> c.shape
     (2, 2, 3)
-    >>> c[1,...]                                   # same as c[1,:,:] or c[1]
+    >>> c[1, ...]  # same as c[1, :, :] or c[1]
     array([[100, 101, 102],
            [110, 112, 113]])
-    >>> c[...,2]                                   # same as c[:,:,2]
+    >>> c[..., 2]  # same as c[:, :, 2]
     array([[  2,  13],
            [102, 113]])
 
@@ -647,7 +647,7 @@ Changing the shape of an array
 
 An array has a shape given by the number of elements along each axis::
 
-    >>> a = np.floor(10*rg.random((3,4)))
+    >>> a = np.floor(10 * rg.random((3, 4)))
     >>> a
     array([[3., 7., 3., 4.],
            [1., 4., 2., 2.],
@@ -661,7 +661,7 @@ the original array::
 
     >>> a.ravel()  # returns the array, flattened
     array([3., 7., 3., 4., 1., 4., 2., 2., 7., 2., 4., 9.])
-    >>> a.reshape(6,2)  # returns the array with a modified shape
+    >>> a.reshape(6, 2)  # returns the array with a modified shape
     array([[3., 7.],
            [3., 4.],
            [1., 4.],
@@ -678,14 +678,14 @@ the original array::
     >>> a.shape
     (3, 4)
 
-The order of the elements in the array resulting from ravel() is
+The order of the elements in the array resulting from ``ravel`` is
 normally "C-style", that is, the rightmost index "changes the fastest",
-so the element after a[0,0] is a[0,1]. If the array is reshaped to some
+so the element after ``a[0, 0]`` is ``a[0, 1]``. If the array is reshaped to some
 other shape, again the array is treated as "C-style". NumPy normally
-creates arrays stored in this order, so ravel() will usually not need to
+creates arrays stored in this order, so ``ravel`` will usually not need to
 copy its argument, but if the array was made by taking slices of another
 array or created with unusual options, it may need to be copied. The
-functions ravel() and reshape() can also be instructed, using an
+functions ``ravel`` and ``reshape`` can also be instructed, using an
 optional argument, to use FORTRAN-style arrays, in which the leftmost
 index changes the fastest.
 
@@ -698,15 +698,15 @@ itself::
     array([[3., 7., 3., 4.],
            [1., 4., 2., 2.],
            [7., 2., 4., 9.]])
-    >>> a.resize((2,6))
+    >>> a.resize((2, 6))
     >>> a
     array([[3., 7., 3., 4., 1., 4.],
            [2., 2., 7., 2., 4., 9.]])
 
-If a dimension is given as -1 in a reshaping operation, the other
+If a dimension is given as ``-1`` in a reshaping operation, the other
 dimensions are automatically calculated::
 
-    >>> a.reshape(3,-1)
+    >>> a.reshape(3, -1)
     array([[3., 7., 3., 4.],
            [1., 4., 2., 2.],
            [7., 2., 4., 9.]])
@@ -726,45 +726,44 @@ Stacking together different arrays
 
 Several arrays can be stacked together along different axes::
 
-    >>> a = np.floor(10*rg.random((2,2)))
+    >>> a = np.floor(10 * rg.random((2, 2)))
     >>> a
     array([[9., 7.],
            [5., 2.]])
-    >>> b = np.floor(10*rg.random((2,2)))
+    >>> b = np.floor(10 * rg.random((2, 2)))
     >>> b
     array([[1., 9.],
            [5., 1.]])
-    >>> np.vstack((a,b))
+    >>> np.vstack((a, b))
     array([[9., 7.],
            [5., 2.],
            [1., 9.],
            [5., 1.]])
-    >>> np.hstack((a,b))
+    >>> np.hstack((a, b))
     array([[9., 7., 1., 9.],
            [5., 2., 5., 1.]])
 
-The function `column_stack`
-stacks 1D arrays as columns into a 2D array. It is equivalent to
-`hstack` only for 2D arrays::
+The function `column_stack` stacks 1D arrays as columns into a 2D array.
+It is equivalent to `hstack` only for 2D arrays::
 
     >>> from numpy import newaxis
-    >>> np.column_stack((a,b))     # with 2D arrays
+    >>> np.column_stack((a, b))  # with 2D arrays
     array([[9., 7., 1., 9.],
            [5., 2., 5., 1.]])
-    >>> a = np.array([4.,2.])
-    >>> b = np.array([3.,8.])
-    >>> np.column_stack((a,b))     # returns a 2D array
+    >>> a = np.array([4., 2.])
+    >>> b = np.array([3., 8.])
+    >>> np.column_stack((a, b))  # returns a 2D array
     array([[4., 3.],
            [2., 8.]])
-    >>> np.hstack((a,b))           # the result is different
+    >>> np.hstack((a, b))        # the result is different
     array([4., 2., 3., 8.])
-    >>> a[:,newaxis]               # view `a` as a 2D column vector
+    >>> a[:, newaxis]  # view `a` as a 2D column vector
     array([[4.],
            [2.]])
-    >>> np.column_stack((a[:,newaxis],b[:,newaxis]))
+    >>> np.column_stack((a[:, newaxis], b[:, newaxis]))
     array([[4., 3.],
            [2., 8.]])
-    >>> np.hstack((a[:,newaxis],b[:,newaxis]))   # the result is the same
+    >>> np.hstack((a[:, newaxis], b[:, newaxis]))  # the result is the same
     array([[4., 3.],
            [2., 8.]])
 
@@ -785,12 +784,10 @@ which the concatenation should happen.
 
 **Note**
 
-In complex cases, `r_` and
-`c_` are useful for creating arrays
-by stacking numbers along one axis. They allow the use of range literals
-(":") ::
+In complex cases, `r_` and `c_` are useful for creating arrays by stacking
+numbers along one axis. They allow the use of range literals ``:``. ::
 
-       >>> np.r_[1:4,0,4]
+       >>> np.r_[1:4, 0, 4]
        array([1, 2, 3, 0, 4])
 
 When used with arrays as arguments,
@@ -818,18 +815,18 @@ array along its horizontal axis, either by specifying the number of
 equally shaped arrays to return, or by specifying the columns after
 which the division should occur::
 
-    >>> a = np.floor(10*rg.random((2,12)))
+    >>> a = np.floor(10 * rg.random((2, 12)))
     >>> a
     array([[6., 7., 6., 9., 0., 5., 4., 0., 6., 8., 5., 2.],
            [8., 5., 5., 7., 1., 8., 6., 7., 1., 8., 1., 0.]])
-    # Split a into 3
-    >>> np.hsplit(a,3)
+    >>> # Split `a` into 3
+    >>> np.hsplit(a, 3)
     [array([[6., 7., 6., 9.],
            [8., 5., 5., 7.]]), array([[0., 5., 4., 0.],
            [1., 8., 6., 7.]]), array([[6., 8., 5., 2.],
            [1., 8., 1., 0.]])]
-    # Split a after the third and the fourth column
-    >>> np.hsplit(a,(3,4))
+    >>> # Split `a` after the third and the fourth column
+    >>> np.hsplit(a, (3, 4))
     [array([[6., 7., 6.],
            [8., 5., 5.]]), array([[9.],
            [7.]]), array([[0., 5., 4., 0., 6., 8., 5., 2.],
@@ -871,7 +868,7 @@ copy.
     >>> def f(x):
     ...     print(id(x))
     ...
-    >>> id(a)                           # id is a unique identifier of an object
+    >>> id(a)  # id is a unique identifier of an object
     148293216  # may vary
     >>> f(a)
     148293216  # may vary
@@ -887,15 +884,15 @@ creates a new array object that looks at the same data.
     >>> c = a.view()
     >>> c is a
     False
-    >>> c.base is a                        # c is a view of the data owned by a
+    >>> c.base is a            # c is a view of the data owned by a
     True
     >>> c.flags.owndata
     False
     >>>
-    >>> c = c.reshape((2, 6))                      # a's shape doesn't change
+    >>> c = c.reshape((2, 6))  # a's shape doesn't change
     >>> a.shape
     (3, 4)
-    >>> c[0, 4] = 1234                      # a's data changes
+    >>> c[0, 4] = 1234         # a's data changes
     >>> a
     array([[   0,    1,    2,    3],
            [1234,    5,    6,    7],
@@ -903,8 +900,8 @@ creates a new array object that looks at the same data.
 
 Slicing an array returns a view of it::
 
-    >>> s = a[ : , 1:3]     # spaces added for clarity; could also be written "s = a[:, 1:3]"
-    >>> s[:] = 10           # s[:] is a view of s. Note the difference between s = 10 and s[:] = 10
+    >>> s = a[:, 1:3]
+    >>> s[:] = 10  # s[:] is a view of s. Note the difference between s = 10 and s[:] = 10
     >>> a
     array([[   0,   10,   10,    3],
            [1234,   10,   10,    7],
@@ -917,12 +914,12 @@ The ``copy`` method makes a complete copy of the array and its data.
 
 ::
 
-    >>> d = a.copy()                          # a new array object with new data is created
+    >>> d = a.copy()  # a new array object with new data is created
     >>> d is a
     False
-    >>> d.base is a                           # d doesn't share anything with a
+    >>> d.base is a  # d doesn't share anything with a
     False
-    >>> d[0,0] = 9999
+    >>> d[0, 0] = 9999
     >>> a
     array([[   0,   10,   10,    3],
            [1234,   10,   10,    7],
@@ -1068,13 +1065,13 @@ Indexing with Arrays of Indices
 
 ::
 
-    >>> a = np.arange(12)**2                       # the first 12 square numbers
-    >>> i = np.array([1, 1, 3, 8, 5])              # an array of indices
-    >>> a[i]                                       # the elements of a at the positions i
+    >>> a = np.arange(12)**2  # the first 12 square numbers
+    >>> i = np.array([1, 1, 3, 8, 5])  # an array of indices
+    >>> a[i]  # the elements of `a` at the positions `i`
     array([ 1,  1,  9, 64, 25])
-    >>>
-    >>> j = np.array([[3, 4], [9, 7]])      # a bidimensional array of indices
-    >>> a[j]                                       # the same shape as j
+    >>> 
+    >>> j = np.array([[3, 4], [9, 7]])  # a bidimensional array of indices
+    >>> a[j]  # the same shape as `j`
     array([[ 9, 16],
            [81, 49]])
 
@@ -1090,9 +1087,9 @@ using a palette.
     ...                     [0, 255, 0],       # green
     ...                     [0, 0, 255],       # blue
     ...                     [255, 255, 255]])  # white
-    >>> image = np.array([[0, 1, 2, 0],        # each value corresponds to a color in the palette
+    >>> image = np.array([[0, 1, 2, 0],  # each value corresponds to a color in the palette
     ...                   [0, 3, 4, 0]])
-    >>> palette[image]                         # the (2, 4, 3) color image
+    >>> palette[image]  # the (2, 4, 3) color image
     array([[[  0,   0,   0],
             [255,   0,   0],
             [  0, 255,   0],
@@ -1108,25 +1105,25 @@ indices for each dimension must have the same shape.
 
 ::
 
-    >>> a = np.arange(12).reshape(3,4)
+    >>> a = np.arange(12).reshape(3, 4)
     >>> a
     array([[ 0,  1,  2,  3],
            [ 4,  5,  6,  7],
            [ 8,  9, 10, 11]])
-    >>> i = np.array([[0, 1],                     # indices for the first dim of a
+    >>> i = np.array([[0, 1],  # indices for the first dim of `a`
     ...               [1, 2]])
-    >>> j = np.array([[2, 1],                     # indices for the second dim
+    >>> j = np.array([[2, 1],  # indices for the second dim
     ...               [3, 3]])
-    >>>
-    >>> a[i, j]                                   # i and j must have equal shape
+    >>> 
+    >>> a[i, j]  # i and j must have equal shape
     array([[ 2,  5],
            [ 7, 11]])
-    >>>
+    >>> 
     >>> a[i, 2]
     array([[ 2,  6],
            [ 6, 10]])
-    >>>
-    >>> a[:, j]                                     # i.e., a[ : , j]
+    >>> 
+    >>> a[:, j]
     array([[[ 2,  1],
             [ 3,  3]],
     <BLANKLINE>
@@ -1142,26 +1139,24 @@ put ``i`` and ``j`` in a ``tuple`` and then do the indexing with that.
 ::
 
     >>> l = (i, j)
-    # equivalent to a[i, j]
+    >>> # equivalent to a[i, j]
     >>> a[l]
     array([[ 2,  5],
            [ 7, 11]])
 
 However, we can not do this by putting ``i`` and ``j`` into an array,
 because this array will be interpreted as indexing the first dimension
-of a.
+of ``a``.
 
 ::
 
     >>> s = np.array([i, j])
-
-    # not what we want
+    >>> # not what we want
     >>> a[s]
     Traceback (most recent call last):
       File "<stdin>", line 1, in <module>
     IndexError: index 3 is out of bounds for axis 0 with size 3
-
-    # same as a[i, j]
+    >>> # same as `a[i, j]`
     >>> a[tuple(s)]
     array([[ 2,  5],
            [ 7, 11]])
@@ -1169,8 +1164,8 @@ of a.
 Another common use of indexing with arrays is the search of the maximum
 value of time-dependent series::
 
-    >>> time = np.linspace(20, 145, 5)                 # time scale
-    >>> data = np.sin(np.arange(20)).reshape(5,4)      # 4 time-dependent series
+    >>> time = np.linspace(20, 145, 5)  # time scale
+    >>> data = np.sin(np.arange(20)).reshape(5, 4)  # 4 time-dependent series
     >>> time
     array([ 20.  ,  51.25,  82.5 , 113.75, 145.  ])
     >>> data
@@ -1179,22 +1174,18 @@ value of time-dependent series::
            [ 0.98935825,  0.41211849, -0.54402111, -0.99999021],
            [-0.53657292,  0.42016704,  0.99060736,  0.65028784],
            [-0.28790332, -0.96139749, -0.75098725,  0.14987721]])
-
-    # index of the maxima for each series
+    >>> # index of the maxima for each series
     >>> ind = data.argmax(axis=0)
     >>> ind
     array([2, 0, 3, 1])
-
-    # times corresponding to the maxima
+    >>> # times corresponding to the maxima
     >>> time_max = time[ind]
-    >>>
-    >>> data_max = data[ind, range(data.shape[1])] # => data[ind[0],0], data[ind[1],1]...
-
+    >>> 
+    >>> data_max = data[ind, range(data.shape[1])]  # => data[ind[0], 0], data[ind[1], 1]...
     >>> time_max
     array([ 82.5 ,  20.  , 113.75,  51.25])
     >>> data_max
     array([0.98935825, 0.84147098, 0.99060736, 0.6569866 ])
-
     >>> np.all(data_max == data.max(axis=0))
     True
 
@@ -1203,7 +1194,7 @@ You can also use indexing with arrays as a target to assign to::
     >>> a = np.arange(5)
     >>> a
     array([0, 1, 2, 3, 4])
-    >>> a[[1,3,4]] = 0
+    >>> a[[1, 3, 4]] = 0
     >>> a
     array([0, 0, 2, 0, 0])
 
@@ -1211,7 +1202,7 @@ However, when the list of indices contains repetitions, the assignment
 is done several times, leaving behind the last value::
 
     >>> a = np.arange(5)
-    >>> a[[0,0,2]]=[1,2,3]
+    >>> a[[0, 0, 2]] = [1, 2, 3]
     >>> a
     array([2, 1, 3, 3, 4])
 
@@ -1219,13 +1210,13 @@ This is reasonable enough, but watch out if you want to use Python's
 ``+=`` construct, as it may not do what you expect::
 
     >>> a = np.arange(5)
-    >>> a[[0,0,2]]+=1
+    >>> a[[0, 0, 2]] += 1
     >>> a
     array([1, 1, 3, 3, 4])
 
 Even though 0 occurs twice in the list of indices, the 0th element is
-only incremented once. This is because Python requires "a+=1" to be
-equivalent to "a = a + 1".
+only incremented once. This is because Python requires ``a += 1`` to be
+equivalent to ``a = a + 1``.
 
 Indexing with Boolean Arrays
 ----------------------------
@@ -1238,18 +1229,18 @@ which ones we don't.
 The most natural way one can think of for boolean indexing is to use
 boolean arrays that have *the same shape* as the original array::
 
-    >>> a = np.arange(12).reshape(3,4)
+    >>> a = np.arange(12).reshape(3, 4)
     >>> b = a > 4
-    >>> b                                          # b is a boolean with a's shape
+    >>> b  # `b` is a boolean with `a`'s shape
     array([[False, False, False, False],
            [False,  True,  True,  True],
            [ True,  True,  True,  True]])
-    >>> a[b]                                       # 1d array with the selected elements
+    >>> a[b]  # 1d array with the selected elements
     array([ 5,  6,  7,  8,  9, 10, 11])
 
 This property can be very useful in assignments::
 
-    >>> a[b] = 0                                   # All elements of 'a' higher than 4 become 0
+    >>> a[b] = 0  # All elements of `a` higher than 4 become 0
     >>> a
     array([[0, 1, 2, 3],
            [4, 0, 0, 0],
@@ -1264,45 +1255,45 @@ set <https://en.wikipedia.org/wiki/Mandelbrot_set>`__:
 
     >>> import numpy as np
     >>> import matplotlib.pyplot as plt
-    >>> def mandelbrot( h,w, maxit=20 ):
+    >>> def mandelbrot(h, w, maxit=20):
     ...     """Returns an image of the Mandelbrot fractal of size (h,w)."""
-    ...     y,x = np.ogrid[ -1.4:1.4:h*1j, -2:0.8:w*1j ]
-    ...     c = x+y*1j
+    ...     y, x = np.ogrid[-1.4:1.4:h*1j, -2:0.8:w*1j]
+    ...     c = x + y * 1j
     ...     z = c
     ...     divtime = maxit + np.zeros(z.shape, dtype=int)
     ...
     ...     for i in range(maxit):
     ...         z = z**2 + c
-    ...         diverge = z*np.conj(z) > 2**2            # who is diverging
-    ...         div_now = diverge & (divtime==maxit)  # who is diverging now
-    ...         divtime[div_now] = i                  # note when
-    ...         z[diverge] = 2                        # avoid diverging too much
+    ...         diverge = z * np.conj(z) > 2**2       # who is diverging
+    ...         div_now = diverge & (divtime == maxit)  # who is diverging now
+    ...         divtime[div_now] = i                    # note when
+    ...         z[diverge] = 2                          # avoid diverging too much
     ...
     ...     return divtime
-    >>> plt.imshow(mandelbrot(400,400))
+    >>> plt.imshow(mandelbrot(400, 400))
 
 The second way of indexing with booleans is more similar to integer
 indexing; for each dimension of the array we give a 1D boolean array
 selecting the slices we want::
 
-    >>> a = np.arange(12).reshape(3,4)
-    >>> b1 = np.array([False,True,True])             # first dim selection
-    >>> b2 = np.array([True,False,True,False])       # second dim selection
-    >>>
-    >>> a[b1,:]                                   # selecting rows
+    >>> a = np.arange(12).reshape(3, 4)
+    >>> b1 = np.array([False, True, True])         # first dim selection
+    >>> b2 = np.array([True, False, True, False])  # second dim selection
+    >>> 
+    >>> a[b1, :]                                   # selecting rows
     array([[ 4,  5,  6,  7],
            [ 8,  9, 10, 11]])
-    >>>
-    >>> a[b1]                                     # same thing
+    >>> 
+    >>> a[b1]                                      # same thing
     array([[ 4,  5,  6,  7],
            [ 8,  9, 10, 11]])
-    >>>
-    >>> a[:,b2]                                   # selecting columns
+    >>> 
+    >>> a[:, b2]                                   # selecting columns
     array([[ 0,  2],
            [ 4,  6],
            [ 8, 10]])
-    >>>
-    >>> a[b1,b2]                                  # a weird thing to do
+    >>> 
+    >>> a[b1, b2]                                  # a weird thing to do
     array([ 4, 10])
 
 Note that the length of the 1D boolean array must coincide with the
@@ -1319,10 +1310,10 @@ obtain the result for each n-uplet. For example, if you want to compute
 all the a+b\*c for all the triplets taken from each of the vectors a, b
 and c::
 
-    >>> a = np.array([2,3,4,5])
-    >>> b = np.array([8,5,4])
-    >>> c = np.array([5,4,6,8,3])
-    >>> ax,bx,cx = np.ix_(a,b,c)
+    >>> a = np.array([2, 3, 4, 5])
+    >>> b = np.array([8, 5, 4])
+    >>> c = np.array([5, 4, 6, 8, 3])
+    >>> ax, bx, cx = np.ix_(a, b, c)
     >>> ax
     array([[[2]],
     <BLANKLINE>
@@ -1339,7 +1330,7 @@ and c::
     array([[[5, 4, 6, 8, 3]]])
     >>> ax.shape, bx.shape, cx.shape
     ((4, 1, 1), (1, 3, 1), (1, 1, 5))
-    >>> result = ax+bx*cx
+    >>> result = ax + bx * cx
     >>> result
     array([[[42, 34, 50, 66, 26],
             [27, 22, 32, 42, 17],
@@ -1356,9 +1347,9 @@ and c::
            [[45, 37, 53, 69, 29],
             [30, 25, 35, 45, 20],
             [25, 21, 29, 37, 17]]])
-    >>> result[3,2,4]
+    >>> result[3, 2, 4]
     17
-    >>> a[3]+b[2]*c[4]
+    >>> a[3] + b[2] * c[4]
     17
 
 You could also implement the reduce as follows::
@@ -1367,12 +1358,12 @@ You could also implement the reduce as follows::
     ...    vs = np.ix_(*vectors)
     ...    r = ufct.identity
     ...    for v in vs:
-    ...        r = ufct(r,v)
+    ...        r = ufct(r, v)
     ...    return r
 
 and then use it as::
 
-    >>> ufunc_reduce(np.add,a,b,c)
+    >>> ufunc_reduce(np.add, a, b, c)
     array([[[15, 14, 16, 18, 13],
             [12, 11, 13, 15, 10],
             [11, 10, 12, 14,  9]],
@@ -1417,33 +1408,26 @@ See linalg.py in numpy folder for more.
     >>> print(a)
     [[1. 2.]
      [3. 4.]]
-
     >>> a.transpose()
     array([[1., 3.],
            [2., 4.]])
-
     >>> np.linalg.inv(a)
     array([[-2. ,  1. ],
            [ 1.5, -0.5]])
-
-    >>> u = np.eye(2) # unit 2x2 matrix; "eye" represents "I"
+    >>> u = np.eye(2)  # unit 2x2 matrix; "eye" represents "I"
     >>> u
     array([[1., 0.],
            [0., 1.]])
     >>> j = np.array([[0.0, -1.0], [1.0, 0.0]])
-
-    >>> j @ j        # matrix product
+    >>> j @ j  # matrix product
     array([[-1.,  0.],
            [ 0., -1.]])
-
     >>> np.trace(u)  # trace
     2.0
-
     >>> y = np.array([[5.], [7.]])
     >>> np.linalg.solve(a, y)
     array([[-3.],
            [ 4.]])
-
     >>> np.linalg.eig(j)
     (array([0.+1.j, 0.-1.j]), array([[0.70710678+0.j        , 0.70710678-0.j        ],
            [0.        -0.70710678j, 0.        +0.70710678j]]))
@@ -1455,7 +1439,7 @@ See linalg.py in numpy folder for more.
     Returns
         The eigenvalues, each repeated according to its multiplicity.
         The normalized (unit "length") eigenvectors, such that the
-        column ``v[:,i]`` is the eigenvector corresponding to the
+        column ``v[:, i]`` is the eigenvector corresponding to the
         eigenvalue ``w[i]`` .
 
 Tricks and Tips
@@ -1496,13 +1480,13 @@ functions ``column_stack``, ``dstack``, ``hstack`` and ``vstack``,
 depending on the dimension in which the stacking is to be done. For
 example::
 
-    >>> x = np.arange(0,10,2)
+    >>> x = np.arange(0, 10, 2)
     >>> y = np.arange(5)
-    >>> m = np.vstack([x,y])
+    >>> m = np.vstack([x, y])
     >>> m
     array([[0, 2, 4, 6, 8],
            [0, 1, 2, 3, 4]])
-    >>> xy = np.hstack([x,y])
+    >>> xy = np.hstack([x, y])
     >>> xy
     array([0, 2, 4, 6, 8, 0, 1, 2, 3, 4])
 
@@ -1530,12 +1514,12 @@ that ``pylab.hist`` plots the histogram automatically, while
     >>> import matplotlib.pyplot as plt
     >>> # Build a vector of 10000 normal deviates with variance 0.5^2 and mean 2
     >>> mu, sigma = 2, 0.5
-    >>> v = rg.normal(mu,sigma,10000)
+    >>> v = rg.normal(mu, sigma, 10000)
     >>> # Plot a normalized histogram with 50 bins
     >>> plt.hist(v, bins=50, density=1)       # matplotlib version (plot)
     >>> # Compute the histogram with numpy and then plot it
     >>> (n, bins) = np.histogram(v, bins=50, density=True)  # NumPy version (no plot)
-    >>> plt.plot(.5*(bins[1:]+bins[:-1]), n)
+    >>> plt.plot(.5 * (bins[1:] + bins[:-1]), n)
 
 
 Further reading