Merge pull request #20336 from timhoffm/doc-module

QuLogic · web-flow · commit a26f9a322c1c · 2021-06-01T02:55:52.000-04:00
Deduplicate color format specification
diff --git a/lib/matplotlib/colors.py b/lib/matplotlib/colors.py
@@ -32,34 +32,8 @@
 "#rrggbb" format (`to_hex`), and a sequence of colors to an (n, 4)
 RGBA array (`to_rgba_array`).  Caching is used for efficiency.
 
-Matplotlib recognizes the following formats to specify a color:
-
-* an RGB or RGBA (red, green, blue, alpha) tuple of float values in closed
-  interval ``[0, 1]`` (e.g., ``(0.1, 0.2, 0.5)`` or ``(0.1, 0.2, 0.5, 0.3)``);
-* a hex RGB or RGBA string (e.g., ``'#0f0f0f'`` or ``'#0f0f0f80'``;
-  case-insensitive);
-* a shorthand hex RGB or RGBA string, equivalent to the hex RGB or RGBA
-  string obtained by duplicating each character, (e.g., ``'#abc'``, equivalent
-  to ``'#aabbcc'``, or ``'#abcd'``, equivalent to ``'#aabbccdd'``;
-  case-insensitive);
-* a string representation of a float value in ``[0, 1]`` inclusive for gray
-  level (e.g., ``'0.5'``);
-* one of the characters ``{'b', 'g', 'r', 'c', 'm', 'y', 'k', 'w'}``, which
-  are short-hand notations for shades of blue, green, red, cyan, magenta,
-  yellow, black, and white. Note that the colors ``'g', 'c', 'm', 'y'`` do not
-  coincide with the X11/CSS4 colors. Their particular shades were chosen for
-  better visibility of colored lines against typical backgrounds.
-* a X11/CSS4 color name (case-insensitive);
-* a name from the `xkcd color survey`_, prefixed with ``'xkcd:'`` (e.g.,
-  ``'xkcd:sky blue'``; case insensitive);
-* one of the Tableau Colors from the 'T10' categorical palette (the default
-  color cycle): ``{'tab:blue', 'tab:orange', 'tab:green', 'tab:red',
-  'tab:purple', 'tab:brown', 'tab:pink', 'tab:gray', 'tab:olive', 'tab:cyan'}``
-  (case-insensitive);
-* a "CN" color spec, i.e. 'C' followed by a number, which is an index into the
-  default property cycle (:rc:`axes.prop_cycle`); the indexing is intended to
-  occur at rendering time, and defaults to black if the cycle does not include
-  color.
+Colors that Matplotlib recognizes are listed at
+:doc:`/tutorials/colors/colors`.
 
 .. _palettable: https://jiffyclub.github.io/palettable/
 .. _xkcd color survey: https://xkcd.com/color/rgb/
diff --git a/lib/matplotlib/legend_handler.py b/lib/matplotlib/legend_handler.py
@@ -3,8 +3,10 @@
 
 .. important::
 
-    It is strongly encouraged to have read the :doc:`legend guide
-    </tutorials/intermediate/legend_guide>` before this documentation.
+    This is a low-level legend API, which most end users do not need.
+
+    We recommend that you are familiar with the :doc:`legend guide
+    </tutorials/intermediate/legend_guide>` before reading this documentation.
 
 Legend handlers are expected to be a callable object with a following
 signature. ::
diff --git a/tutorials/colors/colors.py b/tutorials/colors/colors.py
@@ -3,8 +3,7 @@
 Specifying Colors
 *****************
 
-Matplotlib recognizes the following formats in the table below to specify a
-color.
+Matplotlib recognizes the following formats to specify a color.
 
 +--------------------------------------+--------------------------------------+
 | Format                               | Example                              |
@@ -20,18 +19,20 @@
 | equivalent hex shorthand of          | - ``'#fb1'`` as ``'#ffbb11'``        |
 | duplicated characters.               |                                      |
 +--------------------------------------+--------------------------------------+
-| String representation of float value | - ``'0.8'`` as light gray            |
-| in closed interval ``[0, 1]`` for    | - ``'0'`` as black                   |
-| black and white, respectively.       | - ``'1'`` as white                   |
+| String representation of float value | - ``'0'`` as black                   |
+| in closed interval ``[0, 1]`` for    | - ``'1'`` as white                   |
+| grayscale values.                    | - ``'0.8'`` as light gray            |
 +--------------------------------------+--------------------------------------+
 | Single character shorthand notation  | - ``'b'`` as blue                    |
-| for shades of colors.                | - ``'g'`` as green                   |
+| for some basic colors.               | - ``'g'`` as green                   |
 |                                      | - ``'r'`` as red                     |
-| .. note:: The colors green, cyan,    | - ``'c'`` as cyan                    |
-|           magenta, and yellow do not | - ``'m'`` as magenta                 |
-|           coincide with X11/CSS4     | - ``'y'`` as yellow                  |
-|           colors.                    | - ``'k'`` as black                   |
-|                                      | - ``'w'`` as white                   |
+| .. note::                            | - ``'c'`` as cyan                    |
+|    The colors green, cyan, magenta,  | - ``'m'`` as magenta                 |
+|    and yellow do not coincide with   | - ``'y'`` as yellow                  |
+|    X11/CSS4 colors. Their particular | - ``'k'`` as black                   |
+|    shades were chosen for better     | - ``'w'`` as white                   |
+|    visibility of colored lines       |                                      |
+|    against typical backgrounds.      |                                      |
 +--------------------------------------+--------------------------------------+
 | Case-insensitive X11/CSS4 color name | - ``'aquamarine'``                   |
 | with no spaces.                      | - ``'mediumseagreen'``               |
