From 4893b24867f0bba433f9f55feb74f9b657e4a015 Mon Sep 17 00:00:00 2001
From: Ralf Gommers <ralf.gommers@gmail.com>
Date: Fri, 15 Sep 2023 17:54:17 +0200
Subject: [PATCH] DEV: improve `spin docs` command

Explain how to build a zipfile of the html docs for release purposes.
Remove --install-deps, as that is bad practice and `pip` invocations
for dependencies should not be present in this CLI.

Closes gh-24713
---
 .spin/cmds.py         | 16 +++++-----------
 doc/HOWTO_RELEASE.rst |  9 ++++-----
 2 files changed, 9 insertions(+), 16 deletions(-)

diff --git a/.spin/cmds.py b/.spin/cmds.py
index 656625afe2a9..ea994c38311e 100644
--- a/.spin/cmds.py
+++ b/.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)
 
 
diff --git a/doc/HOWTO_RELEASE.rst b/doc/HOWTO_RELEASE.rst
index 032d51780e9d..d4dbb504ea5d 100644
--- a/doc/HOWTO_RELEASE.rst
+++ b/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