Merge pull request matplotlib#22912 from larsoner/colors

DOC: Better doc of colors

Author: timhoffm

examples/color/named_colors.py

@@ -3,29 +3,31 @@
 List of named colors
 ====================
 
-This plots a list of the named colors supported in matplotlib. Note that
-:ref:`xkcd colors <xkcd-colors>` are supported as well, but are not listed here
-for brevity.
-
+This plots a list of the named colors supported in matplotlib.
 For more information on colors in matplotlib see
 
 * the :doc:`/tutorials/colors/colors` tutorial;
 * the `matplotlib.colors` API;
 * the :doc:`/gallery/color/color_demo`.
+
+----------------------------
+Helper Function for Plotting
+----------------------------
+First we define a helper function for making a table of colors, then we use it
+on some common color categories.
 """
 
 from matplotlib.patches import Rectangle
 import matplotlib.pyplot as plt
 import matplotlib.colors as mcolors
 
 
-def plot_colortable(colors, title, sort_colors=True, emptycols=0):
+def plot_colortable(colors, sort_colors=True, emptycols=0):
 
     cell_width = 212
     cell_height = 22
     swatch_width = 48
     margin = 12
-    topmargin = 40
 
     # Sort colors by hue, saturation, value and name.
     if sort_colors is True:
@@ -41,18 +43,17 @@ def plot_colortable(colors, title, sort_colors=True, emptycols=0):
     nrows = n // ncols + int(n % ncols > 0)
 
     width = cell_width * 4 + 2 * margin
-    height = cell_height * nrows + margin + topmargin
+    height = cell_height * nrows + 2 * margin
     dpi = 72
 
     fig, ax = plt.subplots(figsize=(width / dpi, height / dpi), dpi=dpi)
     fig.subplots_adjust(margin/width, margin/height,
-                        (width-margin)/width, (height-topmargin)/height)
+                        (width-margin)/width, (height-margin)/height)
     ax.set_xlim(0, cell_width * 4)
     ax.set_ylim(cell_height * (nrows-0.5), -cell_height/2.)
     ax.yaxis.set_visible(False)
     ax.xaxis.set_visible(False)
     ax.set_axis_off()
-    ax.set_title(title, fontsize=24, loc="left", pad=10)
 
     for i, name in enumerate(names):
         row = i % nrows
@@ -73,22 +74,38 @@ def plot_colortable(colors, title, sort_colors=True, emptycols=0):
 
     return fig
 
-plot_colortable(mcolors.BASE_COLORS, "Base Colors",
-                sort_colors=False, emptycols=1)
-plot_colortable(mcolors.TABLEAU_COLORS, "Tableau Palette",
-                sort_colors=False, emptycols=2)
+#############################################################################
+# -----------
+# Base colors
+# -----------
 
-# sphinx_gallery_thumbnail_number = 3
-plot_colortable(mcolors.CSS4_COLORS, "CSS Colors")
+plot_colortable(mcolors.BASE_COLORS, sort_colors=False, emptycols=1)
 
-# Optionally plot the XKCD colors (Caution: will produce large figure)
-# xkcd_fig = plot_colortable(mcolors.XKCD_COLORS, "XKCD Colors")
-# xkcd_fig.savefig("XKCD_Colors.png")
+#############################################################################
+# ---------------
+# Tableau Palette
+# ---------------
 
-plt.show()
+plot_colortable(mcolors.TABLEAU_COLORS, sort_colors=False, emptycols=2)
 
+#############################################################################
+# ----------
+# CSS Colors
+# ----------
+
+# sphinx_gallery_thumbnail_number = 3
+plot_colortable(mcolors.CSS4_COLORS)
+plt.show()
 
 #############################################################################
+# -----------
+# XKCD Colors
+# -----------
+# XKCD colors are supported, but they produce a large figure, so we skip them
+# for now. You can use the following code if desired::
+#
+#     xkcd_fig = plot_colortable(mcolors.XKCD_COLORS, "XKCD Colors")
+#     xkcd_fig.savefig("XKCD_Colors.png")
 #
 # .. admonition:: References
 #