Repository navigation
[Doc]: Document color in a consistent way, including link #24859
Description
Documentation Link
No response
Problem
Matplotlib has a rather flexible color concept, see https://matplotlib.org/stable/tutorials/colors/colors.html
In the documentation, the type of color arguments is often, but not always, listed as "color", although there are limited hints what this actually means.
Suggested improvement
Link the type color to the page above (is there a better one?). Update other types (like str) to be color.
:doc:`color </tutorials/colors/colors>`
These are the ones I found through a simple grep.
matplotlib/axes/_axes.py: facecolor : color, default: 'none' matplotlib/axes/_axes.py: edgecolor : color, default: '0.5' matplotlib/axes/_axes.py: color : color or list of color, optional matplotlib/axes/_axes.py: edgecolor : color or list of color, optional matplotlib/axes/_axes.py: ecolor : color or list of color, default: 'black' matplotlib/axes/_axes.py: color : color or list of color, optional matplotlib/axes/_axes.py: edgecolor : color or list of color, optional matplotlib/axes/_axes.py: ecolor : color or list of color, default: 'black' matplotlib/axes/_axes.py: ecolor : color, default: None matplotlib/axes/_axes.py: pcolor : An alternative implementation with slightly different matplotlib/axes/_axes.py: color : color or array-like of colors or None, default: None matplotlib/axes/_base.py: color : color matplotlib/axes/_base.py: color : color matplotlib/axes/_base.py: labelcolor : color matplotlib/axes/_base.py: grid_color : color matplotlib/axes/_secondary_axes.py: color : color matplotlib/backend_bases.py: facecolor : color or 'auto', default: :rc:`savefig.facecolor` matplotlib/backend_bases.py: edgecolor : color or 'auto', default: :rc:`savefig.edgecolor` matplotlib/collections.py: color : color or list of colors, default: :rc:`lines.color` matplotlib/figure.py: color : color matplotlib/figure.py: color : color matplotlib/figure.py: facecolor : default: :rc:`figure.facecolor` matplotlib/figure.py: edgecolor : default: :rc:`figure.edgecolor` matplotlib/figure.py: facecolor : default: :rc:`figure.facecolor` matplotlib/figure.py: edgecolor : default: :rc:`figure.edgecolor` matplotlib/figure.py: facecolor : color or 'auto', default: :rc:`savefig.facecolor` matplotlib/figure.py: edgecolor : color or 'auto', default: :rc:`savefig.edgecolor` matplotlib/legend.py:labelcolor : str or list, default: :rc:`legend.labelcolor` matplotlib/legend.py:facecolor : "inherit" or color, default: :rc:`legend.facecolor` matplotlib/legend.py:edgecolor : "inherit" or color, default: :rc:`legend.edgecolor` matplotlib/lines.py: color : color matplotlib/lines.py: gapcolor : color or None matplotlib/mathtext.py: color : str, optional matplotlib/patches.py: color : color or None matplotlib/patches.py: color : color or None matplotlib/patheffects.py: shadow_color : color, default: 'black' matplotlib/pyplot.py: facecolor : color, default: :rc:`figure.facecolor` matplotlib/pyplot.py: edgecolor : color, default: :rc:`figure.edgecolor` matplotlib/quiver.py:color : color or color sequence, optional matplotlib/quiver.py: color : color matplotlib/quiver.py: labelcolor : color, default: :rc:`text.color` matplotlib/quiver.py:barbcolor : color or color sequence matplotlib/quiver.py:flagcolor : color or color sequence matplotlib/streamplot.py: color : color or 2D array matplotlib/table.py: edgecolor : color matplotlib/table.py: facecolor : color matplotlib/text.py: color : color matplotlib/text.py: color : color matplotlib/widgets.py: color : color matplotlib/widgets.py: hovercolor : color matplotlib/widgets.py: initcolor : color, default: 'r' matplotlib/widgets.py: track_color : color, default: 'lightgrey' matplotlib/widgets.py: track_color : color, default: 'lightgrey' matplotlib/widgets.py: color : color matplotlib/widgets.py: hovercolor : color matplotlib/widgets.py: color : color matplotlib/widgets.py: hovercolor : color matplotlib/widgets.py: activecolor : color matplotlib/widgets.py: activecolor : color mpl_toolkits/axes_grid1/anchored_artists.py: color : str, default: 'black' mpl_toolkits/axes_grid1/anchored_artists.py: color : str, default: 'white' mpl_toolkits/mplot3d/axes3d.py: color : color-like mpl_toolkits/mplot3d/axes3d.py: color : sequence of colors, optional mpl_toolkits/mplot3d/axes3d.py: ecolor : color, default: None mpl_toolkits/mplot3d/axis3d.py: color : color
matplotlib/axes/_axes.py: colors : list of colors, default: :rc:`lines.color`
matplotlib/axes/_axes.py: colors : list of colors, default: :rc:`lines.color`
matplotlib/axes/_axes.py: colors : color or list of colors, default: :rc:`lines.color`
matplotlib/axes/_axes.py: colors : array-like, default: None
matplotlib/axes/_axes.py: edgecolors : color or sequence of color or {'face', 'none'} or None
matplotlib/axes/_axes.py: colors : array(N, 4) or None
matplotlib/axes/_axes.py: edgecolors : {'face', 'none', *None*} or color or sequence of color, \
matplotlib/axes/_axes.py: edgecolors : {'face', 'none', *None*} or color, default: 'face'
matplotlib/axes/_axes.py: edgecolors : {'none', None, 'face', color, color sequence}, optional
matplotlib/axes/_axes.py: edgecolors : {'none', None, 'face', color, color sequence}, optional
matplotlib/axes/_base.py: colors : color
matplotlib/backend_bases.py: colors : (3, 4) array-like
matplotlib/backend_bases.py: colors : (N, 3, 4) array-like
matplotlib/backends/backend_pdf.py: colors : np.ndarray
matplotlib/collections.py: edgecolors : color or list of colors, default: :rc:`patch.edgecolor`
matplotlib/collections.py: facecolors : color or list of colors, default: :rc:`patch.facecolor`
matplotlib/collections.py: colors : color or list of color, default: :rc:`lines.color`
matplotlib/collections.py: facecolors : color or list of color, default: 'none'
matplotlib/colorbar.py: colors : color or list of colors
matplotlib/colors.py: colors : array-like of colors or array-like of (value, color)
matplotlib/colors.py: colors : list, array
matplotlib/colors.py: colors : sequence of colors
matplotlib/contour.py: colors : color or colors or None, default: None
matplotlib/contour.py:colors : color string or sequence of colors, optional
matplotlib/stackplot.py: colors : list of color, optional
matplotlib/tri/_tricontour.py:colors : color string or sequence of colors, optional
matplotlib/tri/_tripcolor.py: facecolors : array-like, optional
mpl_toolkits/mplot3d/axes3d.py: facecolors : array-like of colors.
mpl_toolkits/mplot3d/axes3d.py: facecolors, edgecolors : array-like, optional
matplotlib/axes/_axes.py: c : color or sequence or sequence of color or None matplotlib/backend_bases.py: fg : color matplotlib/collections.py: c : color or list of RGBA tuples matplotlib/collections.py: c : color or list of colors matplotlib/collections.py: c : color or list of colors or 'face' matplotlib/collections.py: c : color or list of colors matplotlib/lines.py: ec : color matplotlib/lines.py: fc : color matplotlib/lines.py: fc : color matplotlib/patches.py: c : color matplotlib/patheffects.py: shadow_rgbFace : color matplotlib/spines.py: c : color mpl_toolkits/mplot3d/axes3d.py: c : color, sequence, or sequence of colors, optional
Activity
story645 commented on Jan 1, 2023
I kinda like how to RGBA spells it out as Matplotlib Color since we don't have a "color" type & I sometimes have been linking out to the tutorials/referenced in the description. Something like
It's a little bit wordier, but is also more explicit that there isn't a specific matplotlib color type.
rcomer commented on Jan 1, 2023
If we wanted to have a color type to link to, I wonder if we could make use of a typing alias, e.g.
ETA: I assume we would eventually want something like that for the type annotations work anyway.
story645 commented on Jan 1, 2023
So there was a GSOD proposing something like that a few years back (link) b/c it makes it easier to document a lot of the parameters if we formalize them as types (and it gives us a logical place to put validation logic) - here's an example for the join and capstyles #18544 & I think there's probably some intersection w/ @ksunden 's work.
I'm just worrying that documenting it in this way right now will imply that we already have an explicit "color" type.
mwaskom commented on Jan 1, 2023
Python typing isn't really sufficient for documenting the color parameter though, because, it doesn't tell you what strings (or floats, although that's easier) are valid.
rcomer commented on Jan 1, 2023
I was thinking that, once you have your (alias) type, you could hang a docstring off it with Color.__doc__ = .... But I admit I haven’t actually checked whether that works…
timhoffm commented on Jan 2, 2023
On a general note: The topic is quite large. It covers at least validation, conversion, normalization (we have no standard how to return colors - often rgb(a) but sometimes also whatever was passed in) and documentation. There has been the idea that an actual Color class would be useful to consolidate these topics. It has to be seen whether that's only for internal use or whether that would be exposed. It's also to be seen whether one wouldwant to document in the docstring of such class or somewhere else. There are also similar cases for other types, e.g. JoinStyle, CapStyle (#18544) and LineStyle (#18664).
Since this is quite a lot, the pragmatic approach is to do this incrementally. Turning color into links similar to the proposal is a good first step. However, I recommend creating a label and using
or (if the section title is not "color")
That's shorter than the tutorial reference and easier to change the target. (The colors tutorial is currently the right target - except that it is not a tutorial. It a reference page, for which we currently do not have a good place in the docs, see also #24746 (comment)).
DOC: Add role for custom informal types like color
DOC: Add role for custom informal types like color