Over at scikit-image we were trying to write a function that would transform a grayscale image into a colormapped image of shape im.shape + (4,), when @tacaswell pointed out that cmap(image) does this already, though this doesn't appear in the MPL docs. It turns out that this is a flaw in sphinx/numpydoc: __call__ is ignored. The method itself is in fact very well documented:

https://github.com/matplotlib/matplotlib/blob/master/lib/matplotlib/colors.py#L525

So that's the first issue:

• fix sphinx/numpydoc/config/documentation so that the above functionality is exposed in the documentation.

The second issue is that we would probably want to use the normalizing version of this, ScalarMappable.to_rgba:

https://github.com/matplotlib/matplotlib/blob/master/lib/matplotlib/cm.py#L211

However, it's actually broken for nD cases, because a 3D image will unnecessarily cause a ValueError (here). So, the second (perhaps optional) issue:

• fix ScalarMappable.to_rgba behavior so that 3D grayscale images (numpy arrays) are supported.

Happy to submit PRs for this but I'd like for some core devs to chime in regarding how best to deal with these... (In particular, I have zero experience with sphinx configuration.)