matplotlib · timhoffm · Sep 24, 2022 · Sep 15, 2022
diff --git a/examples/color/colormap_reference.py b/examples/color/colormap_reference.py
@@ -6,16 +6,17 @@
 Reference for colormaps included with Matplotlib.
 
 A reversed version of each of these colormaps is available by appending
-``_r`` to the name, e.g., ``viridis_r``.
+``_r`` to the name, as shown in :ref:`reverse-cmap`.
 
 See :doc:`/tutorials/colors/colormaps` for an in-depth discussion about
-colormaps, including colorblind-friendliness.
+colormaps, including colorblind-friendliness, and
+:doc:`/tutorials/colors/colormap-manipulation` for a guide to creating
+colormaps.
 """
 
 import numpy as np
 import matplotlib.pyplot as plt
 
-
 cmaps = [('Perceptually Uniform Sequential', [
             'viridis', 'plasma', 'inferno', 'magma', 'cividis']),
          ('Sequential', [
@@ -40,7 +41,6 @@
             'gist_rainbow', 'rainbow', 'jet', 'turbo', 'nipy_spectral',
             'gist_ncar'])]
 
-
 gradient = np.linspace(0, 1, 256)
 gradient = np.vstack((gradient, gradient))
 
@@ -52,7 +52,7 @@ def plot_color_gradients(cmap_category, cmap_list):
     fig, axs = plt.subplots(nrows=nrows, figsize=(6.4, figh))
     fig.subplots_adjust(top=1-.35/figh, bottom=.15/figh, left=0.2, right=0.99)
 
-    axs[0].set_title(cmap_category + ' colormaps', fontsize=14)
+    axs[0].set_title(f"{cmap_category} colormaps", fontsize=14)
 
     for ax, cmap_name in zip(axs, cmap_list):
         ax.imshow(gradient, aspect='auto', cmap=cmap_name)
@@ -67,7 +67,21 @@ def plot_color_gradients(cmap_category, cmap_list):
 for cmap_category, cmap_list in cmaps:
     plot_color_gradients(cmap_category, cmap_list)
 
-plt.show()
+
+###############################################################################
+# .. _reverse-cmap:
+#
+# Reversed colormaps
+# ------------------
+#
+# Append ``_r`` to the name of any built-in colormap to get the reversed
+# version:
+
+plot_color_gradients("Original and reversed ", ['viridis', 'viridis_r'])
+
+# %%
+# The built-in reversed colormaps are generated using `.Colormap.reversed`.
+# For an example, see :ref:`reversing-colormap`
 
 #############################################################################
 #

diff --git a/lib/matplotlib/colors.py b/lib/matplotlib/colors.py
@@ -870,13 +870,13 @@ def reversed(self, name=None):
         """
         Return a reversed instance of the Colormap.
 
-        .. note:: This function is not implemented for base class.
+        .. note:: This function is not implemented for the base class.
 
         Parameters
         ----------
         name : str, optional
-            The name for the reversed colormap. If it's None the
-            name will be the name of the parent colormap + "_r".
+            The name for the reversed colormap. If None, the
+            name is set to ``self.name + "_r"``.
 
         See Also
         --------
@@ -1079,8 +1079,8 @@ def reversed(self, name=None):
         Parameters
         ----------
         name : str, optional
-            The name for the reversed colormap. If it's None the
-            name will be the name of the parent colormap + "_r".
+            The name for the reversed colormap. If None, the
+            name is set to ``self.name + "_r"``.
 
         Returns
         -------
@@ -1179,8 +1179,8 @@ def reversed(self, name=None):
         Parameters
         ----------
         name : str, optional
-            The name for the reversed colormap. If it's None the
-            name will be the name of the parent colormap + "_r".
+            The name for the reversed colormap. If None, the
+            name is set to ``self.name + "_r"``.
 
         Returns
         -------

diff --git a/tutorials/colors/colormap-manipulation.py b/tutorials/colors/colormap-manipulation.py
@@ -255,6 +255,48 @@ def plot_linearmap(cdict):
 
 plot_examples([cmap1, cmap2])
 
+#############################################################################
+# .. _reversing-colormap:
+#
+# Reversing a colormap
+# ====================
+#
+# `.Colormap.reversed` creates a new colormap that is a reversed version of
+# the original colormap.
+
+colors = ["#ffffcc", "#a1dab4", "#41b6c4", "#2c7fb8", "#253494"]
+my_cmap = ListedColormap(colors, name="my_cmap")
+
+my_cmap_r = my_cmap.reversed()
+
+plot_examples([my_cmap, my_cmap_r])
+# %%
+# If no name is passed in, ``.reversed`` also names the copy by
+# :ref:`appending '_r' <registering-colormap>` to the original colormap's
+# name.
+
+##############################################################################
+# .. _registering-colormap:
+#
+# Registering a colormap
+# ======================
+#
+# Colormaps can be added to the `matplotlib.colormaps` list of named colormaps.
+# This allows the colormaps to be accessed by name in plotting functions:
+
+# my_cmap, my_cmap_r from reversing a colormap
+mpl.colormaps.register(cmap=my_cmap)
+mpl.colormaps.register(cmap=my_cmap_r)
+
+data = [[1, 2, 3, 4, 5]]
+
+fig, (ax1, ax2) = plt.subplots(nrows=2)
+
+ax1.imshow(data, cmap='my_cmap')
+ax2.imshow(data, cmap='my_cmap_r')
+
+plt.show()
+
 #############################################################################
 #
 # .. admonition:: References