diff mbox series

[v5,1/4] Makefile: use python3 -m sphinx instead of sphinx-build

Message ID 20260224-fix-make-multi-target-v5-1-7ebf281618b4@cherry.de
State New
Headers show
Series venv migration for docs, migrate Debian/Ubuntu to it, fix epub and latexpdf targets not finding glob images | expand

Commit Message

Quentin Schulz Feb. 24, 2026, 4:32 p.m. UTC 
From: Quentin Schulz <quentin.schulz@cherry.de>

sphinx-build is a "script"[1][2] which is then made available on the
system as a binary, upon installing the sphinx package.

You can have multiple instances of sphinx installed, e.g. system-wide
via the traditional distro package manager or in a venv. In the case of
a venv, if you have sphinx already installed in your host system, source
the venv activate script and then install sphinx via pip inside the
venv, sphinx-build command will still point at the sphinx from the host
system. The work-around is either to run the venv activate script again,
run `hash -r` or `rehash` in your current shell, or call python3 -m
sphinx instead of the Python script.

Let's do the latter as it's the easiest/least-user-facing solution.

This works because python3 interpreter will be the one from the venv,
and it sets the appropriate paths for loading modules (use only packages
from the venv by default, or prefer them if --system-site-packages is
passed).

[1] https://github.com/sphinx-doc/sphinx/blob/v9.1.0/pyproject.toml#L99
[2] https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#creating-executable-scripts

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 documentation/Makefile | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
diff mbox series

Patch

diff --git a/documentation/Makefile b/documentation/Makefile
index e144a50b4..5d9fda501 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -4,7 +4,7 @@ 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
 SPHINXOPTS     ?= -W --keep-going -j auto
-SPHINXBUILD    ?= sphinx-build
+SPHINXBUILD    ?= python3 -m sphinx
 # Release notes are excluded because they contain contributor names and commit messages which can't be modified
 VALEOPTS       ?= --no-wrap --glob '!migration-guides/release-notes-*.rst'
 SOURCEDIR      = .
@@ -16,8 +16,8 @@  DESTDIR        = final
 SVG2PNG        = rsvg-convert
 SVG2PDF        = rsvg-convert
 
-ifeq ($(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi),0)
-$(error "The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed")
+ifeq ($(shell if $(SPHINXBUILD) --version >/dev/null 2>&1; then echo 1; else echo 0; fi),0)
+$(error "Sphinx was not found. Make sure you have it installed")
 endif
 
 # Put it first so that "make" without argument is like "make help".