DEP, DOC: Show deprecated methods in docs and fix overwriting with _deprecated

[AnirudhDagar]

Reference issue

#16846

What does this implement/fix?

• Fix overwriting of docs by only a plain deprecation warning after the usage of scipy._lib.deprecation._deprecated. Now the complete docstring is utilized and one must create a deprecated directive to show the warninng.
• Add back gilbrat and kulsinski to the documentation with appropriate deprecation warning at the top of the docs. Users can follow the suggested alternate method from the deprecation warning (the links should be clickable after soon upgrading to pydata-sphinx-theme>=0.10.0). Note that the removal of NumericalInverseHermite is set for SciPy 1.10.0, hence it is ok to remove it from the toctree. (these were removed in DOC: remove deprecated functions from refguide #16273)
• All deprecated methods running examples with plotting can be added to plot_pre_code warning filtering list in conf.py. DEP: Deprecate scipy.misc in favour of scipy.datasets #15901 will follow the same pattern to avoid failure of the plot directive. Any docstring example with plotting which uses a deprecation function in the future should be added to this list.

[j-bowhay]

Thanks for sorting this! Is it worth adding to the scipy._lib.deprecation._deprecated docstring that it no longer overwrites decorated functions docstring?

[AnirudhDagar]

Is it worth adding to the scipy._lib.deprecation._deprecated docstring that it no longer overwrites decorated functions docstring?

Yes, definitely! I'd recommend using the decorator over the numpy decorator because it is clean, internal, easy to tweak, and avoids repetition of the warning unlike numpy decorator. But before this PR, it was overwriting the docstring which is also not ideal. The .. deprecated directive is the best way to show the dep warning, and hence we need to make sure that scipy._lib.deprecation._deprecated doesn't overwrite the docstring.

[AnirudhDagar]

This is ready for review; some changes here need to be merged first (if everything looks ok) to unblock #15901.

[rgommers]

This all looks good to me, and removing lines from the refguide checker is always a good sign. Thanks @AnirudhDagar.

[AnirudhDagar]

Thanks @rgommers for reviewing and unblocking! 🙌🏼 I can now rebase and update #15901.