From 5ff6b1c2f8f1a602842208264eeaa0a528e14bb0 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Sun, 7 Dec 2025 11:33:56 +0100
Subject: [PATCH] DOC: Discouraged duplicate colormaps

Closes #30796.

State that the use of the colormaps gist_gray, grist_yarg, binary is
discouraged. To be clear: We don't have a plan to depreacte them. Even
though I've decided to remove them from the plotting and only mention
them by name in the admonition to de-emphasize them in the docs and push
 towards the recommended alternatives.
---
 .../examples/color/colormap_reference.py      | 21 ++++++++++++++++---
 galleries/users_explain/colors/colormaps.py   | 21 ++++++++++++++++---
 2 files changed, 36 insertions(+), 6 deletions(-)

diff --git a/galleries/examples/color/colormap_reference.py b/galleries/examples/color/colormap_reference.py
index 6f550161f2e9..2dc091d71a45 100644
--- a/galleries/examples/color/colormap_reference.py
+++ b/galleries/examples/color/colormap_reference.py
@@ -24,9 +24,8 @@
             'YlOrBr', 'YlOrRd', 'OrRd', 'PuRd', 'RdPu', 'BuPu',
             'GnBu', 'PuBu', 'YlGnBu', 'PuBuGn', 'BuGn', 'YlGn']),
          ('Sequential (2)', [
-            'binary', 'gist_yarg', 'gist_gray', 'gray', 'bone', 'pink',
-            'spring', 'summer', 'autumn', 'winter', 'cool', 'Wistia',
-            'hot', 'afmhot', 'gist_heat', 'copper']),
+            'gray', 'bone', 'pink', 'spring', 'summer', 'autumn', 'winter',
+            'cool', 'Wistia', 'hot', 'afmhot', 'gist_heat', 'copper']),
          ('Diverging', [
             'PiYG', 'PRGn', 'BrBG', 'PuOr', 'RdGy', 'RdBu',
             'RdYlBu', 'RdYlGn', 'Spectral', 'coolwarm', 'bwr', 'seismic',
@@ -70,6 +69,22 @@ def plot_color_gradients(cmap_category, cmap_list):
 
 
 # %%
+#
+# .. admonition:: Discouraged
+#
+#    For backward compatibility we additionally support the following colormap
+#    names, which are identical to other builtin colormaps. Their use is
+#    discouraged. Use the suggested replacement instead.
+#
+#    =========  =================================
+#    Colormap   Use identical replacement instead
+#    =========  =================================
+#    gist_gray 	gray
+#    gist_yarg 	gray_r
+#    binary 	gray_r
+#    =========  =================================
+#
+#
 # .. _reverse-cmap:
 #
 # Reversed colormaps
diff --git a/galleries/users_explain/colors/colormaps.py b/galleries/users_explain/colors/colormaps.py
index 026ffc9922e2..55989c258802 100644
--- a/galleries/users_explain/colors/colormaps.py
+++ b/galleries/users_explain/colors/colormaps.py
@@ -161,11 +161,26 @@ def plot_color_gradients(category, cmap_list):
 # an excellent example of this).
 
 plot_color_gradients('Sequential (2)',
-                     ['binary', 'gist_yarg', 'gist_gray', 'gray', 'bone',
-                      'pink', 'spring', 'summer', 'autumn', 'winter', 'cool',
-                      'Wistia', 'hot', 'afmhot', 'gist_heat', 'copper'])
+                     ['gray', 'bone', 'pink', 'spring', 'summer', 'autumn',
+                      'winter', 'cool', 'Wistia', 'hot', 'afmhot', 'gist_heat',
+                      'copper'])
 
 # %%
+# .. admonition:: Discouraged
+#
+#    For backward compatibility we additionally support the following colormap
+#    names, which are identical to other builtin colormaps. Their use is
+#    discouraged. Use the suggested replacement instead.
+#
+#    =========  =================================
+#    Colormap   Use identical replacement instead
+#    =========  =================================
+#    gist_gray 	gray
+#    gist_yarg 	gray_r
+#    binary 	gray_r
+#    =========  =================================
+#
+#
 # Diverging
 # ---------
 #