gnunet-handbook

The GNUnet Handbook
Log | Files | Refs

commit 8ec0884bc8a633c9d6b4ce6c2a8ea59c60f3e968
parent 125a11d9113beac47b8833abeeb23259dad64416
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date:   Thu, 19 Nov 2026 07:50:01 +0100

Build in docker

Diffstat:
A.buildbot/Dockerfile | 30++++++++++++++++++++++++++++++
M.buildbot/build.sh | 50++++++++++++++++++++++++++++++++++++++++++++++----
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 -