Updates colorbar.colorbar to accept a colorizer.Colorizer object, in addition to colorizer.ColorizingArtist. This commit also changes the docs from referencing cm.ScalarMappable to referencing colorizer.ColorizingArtist.

PR summary

With the introduction of colorizer.Colorizer and colorizer.ColorizingArtist (#28658) we have separated the norm→color pipeline from the artist. However, the colorbar API has not been updated since these changes took effect.

Consider this example:

fig, ax = plt.subplots(figsize=(6, 1), layout='constrained')

norm = mpl.colors.Normalize(vmin=5, vmax=10)

fig.colorbar(mpl.cm.ScalarMappable(norm=norm, cmap='cool'),
             cax=ax, orientation='horizontal', label='Some Units')

With the new colorizer API, one would expect be able to replace cm.ScalarMappable above with colorizer.Colorizer, however, this is currently not possible, and one must instead replace cm.ScalarMappable above with colorizer.ColorizingArtist, which requires a colorizer.Colorizer as input.

fig.colorbar(mpl.colorizer.ColorizingArtist(mpl.colorizer.Colorizer(norm=norm, cmap='cool')),
             cax=ax, orientation='horizontal', label='Some Units')

This is despite the fact that the norm→color pipeline is entirely contained in the colorizer, and it fails only because of a single call to self.mappable.get_array() within colorbar.Colorbar().

This PR updates colorbar.colorbar() so that it can accept a colorizer.Colorizer as an alternative to colorizer.ColorizingArtist.

fig.colorbar(mpl.colorizer.Colorizer(norm=norm, cmap='cool'),
             cax=ax, orientation='horizontal', label='Some Units')

The following additional changes are included in this PR:

• Changes the docs from referencing cm.ScalarMappable to colorizer.ColorizingArtist.
• Updates colorbar.Colorbar to the new colorizer API by adding .colorizer as a mutable property on a colorbar.Colorbar [this must be mutable as it is mutable for ColorizingArtist and when it changes on the artist it must change on the colorbar]
• makes the .norm and .cmap of a colorbar properties that get the relevant property from the colorizer. This also makes the explicitly immutable.
• makes the .mappable on a colorbar.Colorbar explicitly immutable.

PR checklist

• new and changed code is tested
• [¹] Plotting related features are demonstrated in an example
• New Features and API Changes are noted with a directive and release note
• Documentation complies with general and docstring guidelines

¹ I would like to update https://matplotlib.org/stable/users/explain/colors/colorbar_only.html and https://matplotlib.org/stable/gallery/images_contours_and_fields/multi_image.html but I think that would benefit from having this PR be implemented first.