+1 for a big fat note in the docs (via .. legacy:: directive),
preferably with a link to a recommended replacement.
-1 for emitting warnings from legacy APIs.

This way, we cater to both legacy uses ("it does the job even though
the author graduated a decade ago") and those who write new code.

When an API is declared legacy, I guess, its development stops. All
remaining bugs and warts are declared features, we promise to keep it
in future versions (until further notice of course, legacy stuff can
migrate to deprecated and removed if needs be), and we only promise to
keep it working. I.e. if it does not compile on a new python version,
we'll try to fix that, but no more. We now have a better way of doing
whatever this thing was doing, come join us working on this new bright
and shiny thing. Or, if you want things which used to work "forever",
great, they keep working just like they did.