Hi all,

We've got a number of (sets of) APIs that we keep around for backwards compatibility reasons, but that are not recommended to use in new code. The way we mark those APIs varies, and often it's not exactly clear that they shouldn't be used.

Examples of legacy APIs:

1. `scipy.fftpack`

2. the functional interface to FITPACK (see, e.g., the Notes section of http://scipy.github.io/devdocs/reference/generated/scipy.interpolate.splev.html)

What do you think about adding a formal API status "legacy", and having a uniform way of marking such APIs? That could be for example a `.. legacy::` reST directive that gives a warning box near the top of the docs.

The benefits would be (a) that it's clearer to end users that there is a better alternative, (b) it's clearer to other projects that they should not copy these APIs (thinking of CuPy, Dask, etc. here), and (c) there is a good intermediate state between "supported" and "deprecated" so that if we're not in agreement on the cost of a deprecation, we can move something to "legacy" instead rather than do nothing.

Thoughts?

Cheers,

Ralf