Reorder kwonly kwargs in Colorbar & related docs.

Move "redundant" kwargs (cmap/norm can be specified via mappable;
orientation/ticklocation can be specified via location) to the end of
the kwarg list and under an "Other Parameters" section.

Also remove mention of Normalize(clip=False);

    imshow(rand(10, 10),
           cmap=mpl.colormaps["viridis"].with_extremes(under="w", over="k"))
    colorbar(extend="both")

seems enough to have over/under colors show up, i.e. no need to fiddle
with the clip parameter.

Author: anntzer

lib/matplotlib/colorbar.py

@@ -226,15 +226,26 @@ class Colorbar:
     mappable : `.ScalarMappable`
         The mappable whose colormap and norm will be used.
 
-        To show the under- and over- value colors, the mappable's norm should
-        be specified as ::
+        To show the colors versus index instead of on a 0-1 scale, set the
+        mappable's norm to ``colors.NoNorm()``.
 
-            norm = colors.Normalize(clip=False)
+    alpha : float
+        The colorbar transparency between 0 (transparent) and 1 (opaque).
+
+    location : None or {'left', 'right', 'top', 'bottom'}
+        Set the colorbar's *orientation* and *ticklocation*. Colorbars on
+        the left and right are vertical, colorbars at the top and bottom
+        are horizontal. The *ticklocation* is the same as *location*, so if
+        *location* is 'top', the ticks are on the top. *orientation* and/or
+        *ticklocation* can be provided as well and overrides the value set by
+        *location*, but there will be an error for incompatible combinations.
 
-        To show the colors versus index instead of on a 0-1 scale, use::
+        .. versionadded:: 3.7
 
-            norm=colors.NoNorm()
+    %(_colormap_kw_doc)s
 
+    Other Parameters
+    ----------------
     cmap : `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
         The colormap to use.  This parameter is ignored, unless *mappable* is
         None.
@@ -243,9 +254,6 @@ class Colorbar:
         The normalization to use.  This parameter is ignored, unless *mappable*
         is None.
 
-    alpha : float
-        The colorbar transparency between 0 (transparent) and 1 (opaque).
-
     orientation : None or {'vertical', 'horizontal'}
         If None, use the value determined by *location*. If both
         *orientation* and *location* are None then defaults to 'vertical'.
@@ -257,40 +265,27 @@ class Colorbar:
         *location*, so a colorbar to the left will have ticks to the left. If
         *location* is None, the ticks will be at the bottom for a horizontal
         colorbar and at the right for a vertical.
-
-    %(_colormap_kw_doc)s
-
-    location : None or {'left', 'right', 'top', 'bottom'}
-        Set the *orientation* and *ticklocation* of the colorbar using a
-        single argument. Colorbars on the left and right are vertical,
-        colorbars at the top and bottom are horizontal. The *ticklocation* is
-        the same as *location*, so if *location* is 'top', the ticks are on
-        the top. *orientation* and/or *ticklocation* can be provided as well
-        and overrides the value set by *location*, but there will be an error
-        for incompatible combinations.
-
-        .. versionadded:: 3.7
     """
 
     n_rasterize = 50  # rasterize solids if number of colors >= n_rasterize
 
-    def __init__(self, ax, mappable=None, *, cmap=None,
-                 norm=None,
-                 alpha=None,
-                 values=None,
-                 boundaries=None,
-                 orientation=None,
-                 ticklocation='auto',
-                 extend=None,
-                 spacing='uniform',  # uniform or proportional
-                 ticks=None,
-                 format=None,
-                 drawedges=False,
-                 extendfrac=None,
-                 extendrect=False,
-                 label='',
-                 location=None,
-                 ):
+    def __init__(
+        self, ax, mappable=None, *,
+        alpha=None,
+        location=None,
+        extend=None,
+        extendfrac=None,
+        extendrect=False,
+        ticks=None,
+        format=None,
+        values=None,
+        boundaries=None,
+        spacing='uniform',
+        drawedges=False,
+        label='',
+        cmap=None, norm=None,  # redundant with *mappable*
+        orientation=None, ticklocation='auto',  # redundant with *location*
+    ):
 
         if mappable is None:
             mappable = cm.ScalarMappable(norm=norm, cmap=cmap)