Repository navigation
DOC: remove numpy.distutils usages from user-facing docs #25597
Description
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.
Activity
eagunn commentedon May 16, 2024
<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 thetoctree::section ofnumpy\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 commentedon May 16, 2024
The f2py documentation page
https://numpy.org/doc/stable/f2py/buildtools/index.html#build-systemsis 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\buildtools1folder would have to be changed to delete distutils reference and eliminate the inclusion ofnumpy\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 commentedon May 17, 2024
Hi @eagunn, thanks for looking into this.
That should be the last task indeed - we should keep the docs as long as we install the
numpy.distutilssubmodule. This issue is more about the docs everywhere else outside of thenumpy.distutilsAPI reference docs.I'd say in all narrative docs/tutorials, we should remove
numpy.distutilsexamples 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 usemesonor to usesetuptools, either way works.eagunn commentedon May 17, 2024
Great feedback @rgommers . Thank you.
I will prepare a PR to pull the
distulilscontent out of the f2py pages. f2py is new and shiny and has all the alternative methods documented already. That change should beclose to trivialreasonably 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
distutilscontent tomesonorsetuptools. 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 commentedon May 17, 2024
Cc @HaoZeke as
f2pymaintainer in case he has more concrete guidance or wishes.That would be a quite useful contribution in itself, thank you.
HaoZeke commentedon May 17, 2024
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.
DOC: remove numpy.distutils references from f2py docs
eagunn commentedon Jun 1, 2024
"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.
-- several mentions in doc/source/f2py/usage.rst
-- one in doc/source/f2py/windows/index.
InessaPawson commentedon Sep 13, 2026
Some of the work has already been completed: the ufunc tutorial mentioned above has been updated to use Meson/meson-python (with setuptools as an alternative).
A good next step would be to audit
doc/sourcefor the remainingnumpy.distutilsreferences and update any user-facing examples or instructions that still recommend it. References that are historical (e.g., release notes or migration documentation) should remain. For active examples, prefer Meson/meson-python where appropriate.frigggga commentedon Sep 24, 2026
hello! I'm part of the NF sustaining the open source series this year, will take a look at this. thanks a lot!