Repository navigation
DOC: remove numpy.distutils usages from user-facing docs #25597
Description
Activity
<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?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?
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 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?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.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.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.Reacted by Anne GunnGreat 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>I will prepare a PR to pull the
distulilscontent out of the f2py pages.Cc @HaoZeke as
f2pymaintainer 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.
Reacted by Anne Gunn- added a commit that references this issue
on May 20, 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.
- 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?
- moved this to Looking for Contributor in NF Sustaining Open Source Series 2026
on 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.hello! I'm part of the NF sustaining the open source series this year, will take a look at this. thanks a lot!
Reacted by Ralf Gommers
numpy.distutilshas been deprecated for a while, and there are better alternatives now. NumPy itself has switched to Meson. Thef2pydocs 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 usesetuptoolsinstead ofnumpy.distutils. The docs should probably simply use Meson in most places, and in cases that are more critical (like forf2py) mention or show that both Meson/meson-python and CMake/scikit-build-core are good options.