DOC: interpolate: deduplicate docstrings in _fitpack_py and _fitpack_impl

[ev-br]

What does this implement/fix?

Functions in _fitpack_py are nothing but thin wrappers which dispatch to either BSpline methods or _fitpack_impl FITPACK Fortran wrappers. Previously, the docstrings were duplicated, and were slightly diverging over time.

So merge the docstrings and deduplicate: move all docstrings to _fitpack_impl/* and attach to _fitpack_py/*.

[ev-br]

Close/reopen to rerun tests

[tupui]

Thanks @ev-br.

In general I am not sure though about dynamic docs. It does not play well with IDEs usually at it would just present an empty box and not follow the redefinition of __doc__.

e.g.

vs

[ev-br]

Hmmmm. This is baffling, I've to admit. The manipulation basically happens on import, so should be safe. Anyway.
Do you know how work make it easier for these IDEs? This certainly is not the only place in scipy we construct docstrings at import time, e.g. in stats.distributions. Does your IDE follow what's done over there?

[ilayn]

IDEs do the analysis on the source code. If you import something then they go and fetch the imported func docstring. So this is an annoyance only if you are directly working on the SciPy codebase itself with bare functions. Otherwise users will see the full docstring.

[tupui]

I am not sure about that. E.g. with stats distributions, it does not render more than what's in the actual docstrings:

This is with PyCharm, maybe some other IDEs behave differently.

[rgommers]

This LGTM once CI is green(er). The IDE issue is an unrelated generic problem and shouldn't block merging this - best to move that to a separate follow-up issue. Probably not much that can be done about that within SciPy though, so it's probably a wontfix.

[tupui]

This LGTM once CI is green(er). The IDE issue is an unrelated generic problem and shouldn't block merging this - best to move that to a separate follow-up issue.

I am not blocking the PR. Just pointing out that this has consequences for IDE users.

Probably not much that can be done about that within SciPy though, so it's probably a wontfix.

I don't think we have made a public decision about going one route or the other. Not using any overwrite for __doc__ would solve the issue (and other issues we have with our own machinery to do so.)

[ev-br]

Just pointing out that this has consequences for IDE users.

This is unfortunate indeed. I guess I wouldn't be surprised if it's a wontfix for pycharm as well, importing stuff online is a big can of worms.

So, to proceed here there are three options:

• keep the status quo. Some 400 lines of duplicated docstrings. Duplicating them was a bad decision (quite a while ago).
• keep this PR as is
• move the docstrings to the functions which end up in the public namespace, i.e. _fitpack_py.py + add code comments to point to where the docstrings are. This is IMO slightly worse than the current state of the PR but is likely OK.

[tupui]

My preference would be option 3 (moving the doc to the public facing API) as to me private functions can then have more maintainers' oriented docs.

[ev-br]

OK, updated to keep all docstrings in _fitpack_py.

[tupui]

Thank you Evgeni 😃 Diff is also simpler to parse, I don't see anything we should wait for in CI before we merge, I will go ahead.