Update colormap usage documentation to prioritize string colormap names

Kaustbh · Kaustbh · commit d3ee967a30f5 · 2024-10-28T01:24:48.000+05:30
diff --git a/doc/users/next_whats_new/diverging_colormaps.rst b/doc/users/next_whats_new/diverging_colormaps.rst
@@ -6,6 +6,11 @@ They are dark-mode diverging colormaps, with minimum lightness at the center,
 and maximum at the extremes. These are taken from F. Crameri's Scientific
 colour maps version 8.0.1 (DOI: https://doi.org/10.5281/zenodo.1243862).
 
+.. note::
+    For `cmap` arguments, we recommend using string colormap names (e.g., `cmap="berlin"`).
+    This is both readable and concise. If an explicit colormap instance is needed, use
+    `plt.colormaps["berlin"]`. The `plt.cm.*` syntax is less scalable, as it only supports
+    built-in colormaps and not user-registered ones.
 
 .. plot::
     :include-source: true
@@ -19,6 +24,6 @@ colour maps version 8.0.1 (DOI: https://doi.org/10.5281/zenodo.1243862).
     img = np.sin(x*y)
 
     _, ax = plt.subplots(1, 3)
-    ax[0].imshow(img, cmap=plt.cm.berlin)
-    ax[1].imshow(img, cmap=plt.cm.managua)
-    ax[2].imshow(img, cmap=plt.cm.vanimo)
+    ax[0].imshow(img, cmap="berlin")
+    ax[1].imshow(img, cmap="managua")
+    ax[2].imshow(img, cmap="vanimo")
