Yes, it's a little late here ...

I've made this a pending deprecation, which feels a bit better than a very long deprecation period.

--> Means we'll still have to deprecate explicitly in a later version.

PendingDeprecationWarning was not playing nicely with sphinx (warnings causing sphinx to fail). I suppose we'd have to include special handing for that.

Instead of a PendingDeprecationWarning I went back to only discouraging this code. In both cases we'd have to add a DeprecationWarning to later releases if we want to finally remove it. So there's no real benefit of the pending deprecation warning.

Macos test failure seems unrelated (subprocess timed out).

@dstansby I think that CI is happier now...