Improve deprecation documentation. Closes #7643

[ngoldbaum]

This improves the deprecation warnings printed by axes.hold and plt.hold and adds a mention of the deprecation of the spectral colormap to the API changes document.

[NelleV]

LGTM. Thanks for the patch!

[efiring]

My reading of the deprecation decorator code is that if you want to use your own message, you would normally include some format strings. At present I think your PR is discarding the version information.

Actually, it looks to me like the underlying _generate_deprecation_message is broken by indentation errors, at the very least... It is not doing the substitutions it should if a message is given.

[NelleV]

@efiring There are two deprecation messages. Which one are you talking about?

[efiring]

Both of them. Same problem. The first one could be helpful if it included the necessary format strings, and if the _generate_deprecation_message bug were fixed. The second one is pointless, providing less information than what it replaces.

[NelleV]

The deprecation messages don't strike me as being less informative. IMO, it is quite the opposite.

[efiring]

@NelleV you are correct; given that the decorator replaces the default message with the one supplied as an argument, ignoring all other arguments, this PR does provide more information. I had an incorrect expectation of what the decorator would do in this case. (Nevertheless, it is broken in that it can't presently be used as intended, taking advantage of its arguments via format strings in the message).

[ngoldbaum]

Yes, I noticed last night that the format string magic wasn't working.

[tacaswell]

appveyor failure looks transient.

[tacaswell]

Thanks @ngoldbaum !

backported to v2.x as 4f0d2ee

[efiring]

See also #7651.