commit 8ec0884bc8a633c9d6b4ce6c2a8ea59c60f3e968
parent 125a11d9113beac47b8833abeeb23259dad64416
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Thu, 19 Nov 2026 07:50:01 +0100
Build in docker
Diffstat:
2 files changed, 76 insertions(+), 4 deletions(-)
diff --git a/.buildbot/Dockerfile b/.buildbot/Dockerfile
@@ -0,0 +1,30 @@
+# Toolchain for building the handbook, used by .buildbot/build.sh.
+#
+# The image holds only the tools; build.sh mounts the checkout and runs
+# sphinx-multiversion over its git refs. Everything comes from Debian
+# trixie, so the result is the same as a build on a trixie host with
+# these packages installed: Sphinx 8.1.3, sphinx-rtd-theme 3.0.2 and
+# sphinx-multiversion 0.2.4.
+#
+# sphinx-multiversion builds every version with the conf.py, _exts/,
+# _templates/ and _static/ of the checkout, so no other theme is needed
+# for older branches that name one in their own conf.py.
+
+FROM docker.io/library/debian:trixie
+
+ENV DEBIAN_FRONTEND=noninteractive \
+ LANG=C.UTF-8
+
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends \
+ git \
+ python3-sphinx \
+ python3-sphinx-multiversion \
+ python3-sphinx-rtd-theme \
+ sphinx-multiversion \
+ && rm -rf /var/lib/apt/lists/*
+
+# Under docker the mounted checkout is owned by the host user rather than
+# by the user in the container, and git refuses to read a repository owned
+# by someone else.
+RUN git config --system --add safe.directory '*'
diff --git a/.buildbot/build.sh b/.buildbot/build.sh
@@ -1,5 +1,15 @@
#!/bin/bash
+# Build the handbook for every version branch with sphinx-multiversion,
+# using the toolchain from .buildbot/Dockerfile. The result goes to _build/.
+#
+# Uses docker, or podman if there is no docker; set CONTAINER_ENGINE to
+# choose.
+
+set -o pipefail
+
+cd "$(dirname "$0")/.." || exit 1
+
git branch -r \
| grep -v '\->' \
| sed "s,\x1B\[[0-9;]*[a-zA-Z],,g" \
@@ -7,12 +17,44 @@ git branch -r \
git branch --track "${remote#origin/}" "$remote"; \
done
-# Conditional extens switch in config
-export SPHINX_MULTIVERSION=1
-
git tag --delete latest || echo "Deleting tag can fail"
# Get latest version branch
latest=$(git for-each-ref --format "%(refname)" | grep -i '^refs/remotes/origin/v[0-9]*\.[0-9]*\.x$' | sort -r | head -n1)
echo $latest" is latest ref"
git tag latest $latest
-sphinx-multiversion . _build
+
+if [ -z "${CONTAINER_ENGINE:-}" ]; then
+ if command -v docker > /dev/null; then
+ CONTAINER_ENGINE=docker
+ else
+ CONTAINER_ENGINE=podman
+ fi
+fi
+image=gnunet-handbook-build
+
+"$CONTAINER_ENGINE" build -t "$image" .buildbot || exit 1
+
+# The checkout is mounted read-only at the same path as on the host, and
+# sphinx-multiversion reads the branches and the tag set up above from its
+# .git. The output comes back as a tar stream on stdout (so Sphinx's own
+# output goes to stderr) and is unpacked here, so that _build/ belongs to
+# the user running this script whichever user the container runs as.
+#
+# SPHINX_MULTIVERSION is the conditional extension switch in conf.py.
+# GNUNET_VERSION (read by conf.py) and SOURCE_DATE_EPOCH (read by Sphinx)
+# are passed on if they are set. conf.py also puts the current year into
+# the copyright notice, so the container gets the host's time zone, or the
+# two would disagree about the year around New Year.
+tz=()
+if [ -e /etc/localtime ]; then
+ tz=(--volume /etc/localtime:/etc/localtime:ro)
+fi
+mkdir -p _build
+"$CONTAINER_ENGINE" run --rm --network=none \
+ --volume "$PWD:$PWD:ro" --workdir "$PWD" "${tz[@]}" \
+ --env SPHINX_MULTIVERSION=1 \
+ --env GNUNET_VERSION \
+ --env SOURCE_DATE_EPOCH \
+ "$image" \
+ sh -c 'sphinx-multiversion . /tmp/_build >&2 && tar -C /tmp/_build -cf - .' \
+ | tar -C _build -xf -