Merge pull request #24718 from rgommers/doc-update

DOC: fix a few doc build issues on 1.26.x and update `spin docs` command/docs

.spin/cmds.py

@@ -75,13 +75,8 @@ def build(ctx, meson_args, jobs=None, clean=False, verbose=False):
     default="auto",
     help="Number of parallel build jobs"
 )
-@click.option(
-    "--install-deps/--no-install-deps",
-    default=False,
-    help="Install dependencies before building"
-)
 @click.pass_context
-def docs(ctx, sphinx_target, clean, first_build, jobs, install_deps):
+def docs(ctx, sphinx_target, clean, first_build, jobs):
     """📖 Build Sphinx documentation
 
     By default, SPHINXOPTS="-W", raising errors on warnings.
@@ -97,13 +92,12 @@ def docs(ctx, sphinx_target, clean, first_build, jobs, install_deps):
 
       spin docs TARGET
 
-    """
-    if sphinx_target not in ('targets', 'help'):
-        if install_deps:
-            util.run(['pip', 'install', '-q', '-r', 'doc_requirements.txt'])
+    E.g., to build a zipfile of the html docs for distribution:
+
+      spin docs dist
 
+    """
     meson.docs.ignore_unknown_options = True
-    del ctx.params['install_deps']
     ctx.forward(meson.docs)
 
 

doc/HOWTO_RELEASE.rst

@@ -100,12 +100,11 @@ github actions.
 
 Building docs
 -------------
-We are no longer building ``PDF`` files. All that will be needed is
+We are no longer building pdf files, only html docs. The ``numpy-html.zip``
+needed to upload to the doc server can be built with ``spin docs dist``.
 
-- virtualenv (pip).
-
-The other requirements will be filled automatically during the documentation
-build process.
+To install the necessary doc build dependencies into your development
+environment, run ``pip install -r doc_requirements.txt``.
 
 
 Uploading to PyPI

doc/source/reference/random/examples/cython/index.rst

@@ -4,8 +4,12 @@
 Extending `numpy.random` via Cython
 -----------------------------------
 
+.. _note:
+
+Starting with NumPy 1.26.0, Meson is the default build system for NumPy.
+See :ref:`distutils-status-migration`.
 
 .. toctree::
-    setup.py.rst
+    meson.build.rst
     extending.pyx
     extending_distributions.pyx

doc/source/reference/random/examples/cython/setup.py.rst → doc/source/reference/random/examples/cython/meson.build.rst

@@ -1,5 +1,5 @@
-setup.py
---------
+meson.build
+-----------
 
-.. literalinclude:: ../../../../../../numpy/random/_examples/cython/setup.py
+.. literalinclude:: ../../../../../../numpy/random/_examples/cython/meson.build
     :language: python

doc/source/user/building.rst

@@ -51,7 +51,7 @@ Building NumPy requires the following software installed:
    can be used, including optimized LAPACK libraries such as OpenBLAS or MKL.
    The choice and location of these libraries as well as include paths and
    other such build options can be specified in a ``.pc`` file, as documented in
-   :ref:`scipy:using-pkg-config-to-detect-libraries-in-a-nonstandard-location`.
+   :ref:`scipy:building-blas-and-lapack`.
 
 4) Cython
 
@@ -138,7 +138,7 @@ file.
 Cross compilation
 -----------------
 
-For cross compilation instructions, see :doc:`scipy:cross_compilation` and the
-`Meson documentation <meson>`_.
+For cross compilation instructions, see :doc:`scipy:building/cross_compilation`
+and the `Meson documentation <meson>`_.
 
 .. _meson: https://mesonbuild.com/Cross-compilation.html#cross-compilation