Looking at the default values in rcParams the default value actually seems to be 'auto', so I think changing 'flat' to 'auto' in the docstring would fix this.

I don't think 'auto' actually needs to be written out, see https://matplotlib.org/devdocs/devel/documenting_mpl.html#rcparams / https://matplotlib.org/devdocs/devel/documenting_mpl.html#default-values

@dstansby, are you suggesting that the docstring should be simply

The fill style for the quadrilateral; defaults to :rc:`pcolor.shading`.

?

I think so, though I am not 100% sure that I agree with this admonition because for non-rendered docs this doesn't help the user much. I somewhat prefer

defaults to :rc:`pcolor.shading` (usually 'auto')

but of course manually typing it makes it susceptible to being forgotten next time behaviour changes.

I think so, though I am not 100% sure that I agree with this admonition because for non-rendered docs this doesn't help the user much. I somewhat prefer

defaults to :rc:`pcolor.shading` (usually 'auto')

but of course manually typing it makes it susceptible to being forgotten next time behaviour changes.

Because of this syncing issue, we do not do this. Also as of now, this would render to HTML as

defaults to rcParams['pcolor'.shading'] (default: 'auto') (usually 'auto')

which would be really confusing.

If somebody wants explicitly written defaults in the source, they need to adapt the :rc: admonition. And I highly recommend only doing that if you additionally add instrumentation to validate the correct defaults in CI.