DOC: remove `numpy.distutils` usages from user-facing docs

[rgommers]

numpy.distutils has been deprecated for a while, and there are better alternatives now. NumPy itself has switched to Meson. The f2py docs go above and beyond already and show how to use Meson, CMake and scikit-build: https://numpy.org/doc/stable/f2py/buildtools/index.html#build-systems.

Here is one example that is still using numpy.distutils: https://numpy.org/doc/stable/user/c-info.ufunc-tutorial.html. There may be others. It'd be fine to keep some docs around that use setuptools instead of numpy.distutils. The docs should probably simply use Meson in most places, and in cases that are more critical (like for f2py) mention or show that both Meson/meson-python and CMake/scikit-build-core are good options.

[eagunn]

<I'm a new wanna-be contributor. I've been looking into this issue as a stepping stone for understanding more about the Sphinx-generated documentation. I thought I'd add one or more comments/questions here as breadcrumbs for anyone who decides to tackle this Task.>

When I grep through the .HTML files generated from my doc build, I see numpy.distutils appear on a huge number of pages. But that turns out to be only in the TOC sidebar.

Question: Would a small but significant step in the right direction be to simply remove numpy.distutils <distutils> from the toctree:: section of numpy\doc\source\reference\module_structure.rst? Or does that need to be the last change in the Task since as long as any documentation refers to the module it should continue to appear in the Module Structure index?

[eagunn]

The f2py documentation page https://numpy.org/doc/stable/f2py/buildtools/index.html#build-systems is referenced by the OP as a good example of documenting non-distutils build options.

However, if we are to remove all references entirely, then various files in the numpy\doc\source\f2py\buildtools1 folder would have to be changed to delete distutils reference and eliminate the inclusion of numpy\doc\source\f2py\buildtools\distutils.rst.

Question: Is the best practice to keep on mentioning distutils but, as the f2py documentation does, point out it is going away and give all the better options? Or has the time come to simply delete distutils references entirely?

[rgommers]

Hi @eagunn, thanks for looking into this.

Question: Would a small but significant step in the right direction be to simply remove numpy.distutils <distutils> from the toctree:: section of numpy\doc\source\reference\module_structure.rst? Or does that need to be the last change in the Task since as long as any documentation refers to the module it should continue to appear in the Module Structure index?

That should be the last task indeed - we should keep the docs as long as we install the numpy.distutils submodule. This issue is more about the docs everywhere else outside of the numpy.distutils API reference docs.

Question: Is the best practice to keep on mentioning distutils but, as the f2py documentation does, point out it is going away and give all the better options? Or has the time come to simply delete distutils references entirely?

I'd say in all narrative docs/tutorials, we should remove numpy.distutils examples completely. It doesn't have to be so comprehensive as for f2py (which is a bit special as it's a build tool). An example like https://numpy.org/doc/stable/user/c-info.ufunc-tutorial.html can be either translated to use meson or to use setuptools, either way works.

[eagunn]

Great feedback @rgommers . Thank you.

I will prepare a PR to pull the distulils content out of the f2py pages. f2py is new and shiny and has all the alternative methods documented already. That change should be close to trivial reasonably simple* and, I hope, would be a good first PR for me to walk through the process.

As for the other pages, I will probably opt to do no harm. I don't know enough yet to translate the distutils content to meson or setuptools. But I'll try to at least make an inventory of all the locations that require fixing, which might save the next person working on this issue a bit of startup time.

<humor>*Update: I've been sufficiently punished for using the T word about a) a project new to me and b) any codebase this big. Three days and many hours later, I'm still working on my first commit. It's not the code. It's me.</humor>

[rgommers]

I will prepare a PR to pull the distulils content out of the f2py pages.

Cc @HaoZeke as f2py maintainer in case he has more concrete guidance or wishes.

which might save the next person working on this issue a bit of startup time.

That would be a quite useful contribution in itself, thank you.

[HaoZeke]

This all sounds like a good plan. Please feel free to ping me on any PRs arising from this effort for a review and also, @eagunn, I'd be happy to help with any issues arising from a translation on a draft PR as well.

[eagunn]

"Inventory" -- I'm traveling and not in a position to make/test changes, but I am reading through docs as I have time. My plan is to add to this comment as I find references to distutils that may need to be changed. NB: Items might already be resolved in some branch/PR; I'm checking them against main as I list them.

• The Scope doc, numpy/doc/neps/scope.rst: In the bullet "NumPy provides some infrastructure for other packages in the scientific Python ecosystem" lists numpy.distutils and does not mention meson.
• In my comments for PR [WIP] DOC: remove numpy.distutils references from f2py docs #26490, I noted that changes to the following two docs should probably be included in that PR but I don't know enough to make/verify changes to examples in the usage doc:
  -- several mentions in doc/source/f2py/usage.rst
  -- one in doc/source/f2py/windows/index.
• /devdocs/reference/module_structure.html notes distutils is deprecated -- it might be worth a pointer to a page on meson or on the transition from distutils to meson
• devdocs has a whole page on distutils, devdocs/reference/distutils.html, presumably the warnings at the top should be modified to nudge the reader towards meson?