DOC: unify `np.transpose`, `np.ndarray.transpose`, and `np.ndarray.T` (#21997)

Better organize and improve cross referencing between the various transpose
functions/methods.

Co-authored-by: Rohit Goswami <r95g10@gmail.com>

1 files changed, 37 insertions, 29 deletions

diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py
index 6e0da47ca..36ddaa8f0 100644
--- a/numpy/core/fromnumeric.py
+++ b/numpy/core/fromnumeric.py
@@ -601,59 +601,67 @@ def _transpose_dispatcher(a, axes=None):
 @array_function_dispatch(_transpose_dispatcher)
 def transpose(a, axes=None):
     """
-    Reverse or permute the axes of an array; returns the modified array.
-
-    For an array a with two axes, transpose(a) gives the matrix transpose.
-
-    Refer to `numpy.ndarray.transpose` for full documentation.
+    Returns an array with axes transposed.
+
+    For a 1-D array, this returns an unchanged view of the original array, as a
+    transposed vector is simply the same vector.
+    To convert a 1-D array into a 2-D column vector, an additional dimension
+    must be added, e.g., ``np.atleast2d(a).T`` achieves this, as does
+    ``a[:, np.newaxis]``.
+    For a 2-D array, this is the standard matrix transpose.
+    For an n-D array, if axes are given, their order indicates how the
+    axes are permuted (see Examples). If axes are not provided, then
+    ``transpose(a).shape == a.shape[::-1]``.
 
     Parameters
     ----------
     a : array_like
         Input array.
     axes : tuple or list of ints, optional
-        If specified, it must be a tuple or list which contains a permutation of
-        [0,1,..,N-1] where N is the number of axes of a.  The i'th axis of the
-        returned array will correspond to the axis numbered ``axes[i]`` of the
-        input.  If not specified, defaults to ``range(a.ndim)[::-1]``, which
-        reverses the order of the axes.
+        If specified, it must be a tuple or list which contains a permutation
+        of [0,1,...,N-1] where N is the number of axes of `a`. The `i`'th axis
+        of the returned array will correspond to the axis numbered ``axes[i]``
+        of the input. If not specified, defaults to ``range(a.ndim)[::-1]``,
+        which reverses the order of the axes.
 
     Returns
     -------
     p : ndarray
-        `a` with its axes permuted.  A view is returned whenever
-        possible.
+        `a` with its axes permuted. A view is returned whenever possible.
 
     See Also
     --------
-    ndarray.transpose : Equivalent method
-    moveaxis
-    argsort
+    ndarray.transpose : Equivalent method.
+    moveaxis : Move axes of an array to new positions.
+    argsort : Return the indices that would sort an array.
 
     Notes
     -----
-    Use `transpose(a, argsort(axes))` to invert the transposition of tensors
+    Use ``transpose(a, argsort(axes))`` to invert the transposition of tensors
     when using the `axes` keyword argument.
 
-    Transposing a 1-D array returns an unchanged view of the original array.
-
     Examples
     --------
-    >>> x = np.arange(4).reshape((2,2))
-    >>> x
-    array([[0, 1],
-           [2, 3]])
+    >>> a = np.array([[1, 2], [3, 4]])
+    >>> a
+    array([[1, 2],
+           [3, 4]])
+    >>> np.transpose(a)
+    array([[1, 3],
+           [2, 4]])
 
-    >>> np.transpose(x)
-    array([[0, 2],
-           [1, 3]])
+    >>> a = np.array([1, 2, 3, 4])
+    >>> a
+    array([1, 2, 3, 4])
+    >>> np.transpose(a)
+    array([1, 2, 3, 4])
 
-    >>> x = np.ones((1, 2, 3))
-    >>> np.transpose(x, (1, 0, 2)).shape
+    >>> a = np.ones((1, 2, 3))
+    >>> np.transpose(a, (1, 0, 2)).shape
     (2, 1, 3)
 
-    >>> x = np.ones((2, 3, 4, 5))
-    >>> np.transpose(x).shape
+    >>> a = np.ones((2, 3, 4, 5))
+    >>> np.transpose(a).shape
     (5, 4, 3, 2)
 
     """