Problem

Pulled out from #31178 (comment) so that this does not get lost.

better document the current song-and-dance necessary to make this work. The current docs are not too helpful:

• https://matplotlib.org/stable/users/explain/colors/colorbar_only.html#discrete-and-extended-colorbar-with-continuous-colorscale is primarly about the colorbar, and uses pre-defined custom bounds
• https://matplotlib.org/stable/users/explain/colors/colorbar_only.html#colorbar-with-arbitrary-colors same - with some overlap to the above
• https://matplotlib.org/stable/users/explain/colors/colormap-manipulation.html#creating-listed-colormaps does not reasonable distinguish the use cases of ListedColormap listing as an approximation vs. listing as discrete colors. Also, the discrete case hides the mapping complication by specifying vmin=..., vmax=....
• https://matplotlib.org/stable/users/explain/colors/colormapnorms.html#discrete-bounds again uses discretization on continuous data, which is actually there rarer application and different from discrete colors for discrete values.
• We could use a simplified version of the above as an example "scatter with discrete colors"

Suggested improvement

Possibly rewrite / restructure above docs.

Depending on how fast we advance with #31195 it may make sense not to invest too much time into this right now, because that will again change the aproach.