DOC: Update building docs to use Meson #24573
Conversation
melissawm
added
04 - Documentation
Meson
melissawm
force-pushed
the
meson-docs
branch
2 times, most recently
from
07cf915
to
60da2d7
Compare
There was a problem hiding this comment.
Thanks Melissa! This looks good to me to merge, after the minor open comments from Rohit and me are addressed. Larger changes can be done in follow-up PRs, this is already very helpful.
What to do with the custom blas/lapack instructions? (I know we talked about ditching those in favor of the SciPy documentation but our docs seem much more detailed and I'm hesitant to just delete.
None of that applies anymore, and there's no replacement right now beyond what's in the SciPy docs. So it should be deleted. Once there are replacement CLI flags, I'll add them to the docs in the same PR as their implementation.
I haven't updated https://numpy.org/doc/stable/dev/development_advanced_debugging.html yet, could do it on a follow-up or on a separate commit.
That's fine. That section looks a bit out of date, it'd need more work beyond updating the couple of runtests.py usages (e.g., use of sanitizers changed/improved). I think we can leave that alone here, and perhaps ask Nathan or Sebastian to update it.
There are a couple of mentions to site.cfg that I didn't remove yet either since I'm not 100% sure of the replacement (if any).
The replacement is a .pc file, as documented in http://scipy.github.io/devdocs/building/blas_lapack.html#using-pkg-config-to-detect-libraries-in-a-nonstandard-location.
I haven't completely redone the docs to mirror SciPy as I still feel there is justification for the current organization, but I'm happy to reconsider.
I think that's fine to leave for now, but my opinion is still that there's very little of value here. The build options really are pretty much identical. Organization wise, I find the NumPy docs very difficult to navigate (e.g., both the sidebar and the start of the page contents at https://numpy.org/devdocs/dev/index.html are very confusing). In addition, the NumPy docs don't help the user/contributor with system dependencies for Windows/macOS/Linux, using conda, other system dependencies, or a simple quickstart to contributing. And things like pip install build_dependencies.txt without taking into account conda users are just plain wrong and will break the contributors environment.
I'm not seeing what to retain from the current docs, but I think you have some concrete sections in mind. I suggest opening a new follow-up issue to identify those. I can't say much more without knowing what those sections are.
After this gets merged I'll try to do it as a followup. |
|
Here's a second take - I believe I adressed most of the comments, let me know if there's anything else that is needed. |
Removes mentions of runtests.py when appropriate and replaces them with equivalent spin commands. [skip travis][skip azp][skip cirrus]
[skip cirrus] [skip azp] [skip actions]
There was a problem hiding this comment.
Thanks @melissawm, the updates looked good. On a closer read I found some more issues with detailed commands, and one conceptual one (use of spin in the user guide rather than the contribution guidelines). I'll push some fixes.
doc/source/user/building.rst
Outdated
| *Note: for build instructions to do development work on NumPy itself, see* | ||
| :ref:`development-environment`. | ||
| To build NumPy with meson, you can use the | ||
| `spin <https://github.com/scientific-python/spin>`_ utility. First, install the |
There was a problem hiding this comment.
This doesn't look right. spin should only be used in the development/contribution instructions, it is not useful to users who simply want to build from source. And it doesn't have the -n/--no-build flag like runtests.py does, so it can't be used right now to run the tests on a numpy package installed in the user's environment.
|
Thanks for catching those! |
Removes mentions of runtests.py when appropriate and replaces them with equivalent spin commands (or pytest in a few cases). [skip azp] Co-authored-by: Ralf Gommers <ralf.gommers@gmail.com>
Removes mentions of runtests.py when appropriate and replaces them with equivalent spin commands (or pytest in a few cases). [skip azp] Co-authored-by: Ralf Gommers <ralf.gommers@gmail.com>
Removes mentions of runtests.py when appropriate and replaces them with equivalent spin commands.
A few pending questions:
I haven't completely redone the docs to mirror SciPy as I still feel there is justification for the current organization, but I'm happy to reconsider.
Partly addresses #23981