[PATCH 0/8] Parallel docs build improvements

[PATCH 0/8] Parallel docs build improvements

[Antonin Godard]

The aim of this series is to take the work of Quentin[1] and with
additional commit that improve the concurrent safety of the docs build,
and some general improvements to the build-docs-container script.

This allows building the docs on all supported distros with this bash
snippet:

```
declare -a distros=( $(./documentation/tools/build-docs-container supported_distros) )

for distro in "${distros[@]}"; do
  ./documentation/tools/build-docs-container $distro "$target" >/tmp/docs-build-"$distro".log 2>&1 &
done

wait
```

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
Antonin Godard (6):
      tools/build-docs-container: build in separate directory for each distro
      tools/build-docs-container: create symlink to latest build output
      Makefile: wrap set_versions.py with flock
      tools/build-docs-container: allow running non-interactively
      tools/build-docs-container: allow passing extra args to $OCI run
      tools/build-docs-container: make it possible to print the distro list

Quentin Schulz (2):
      tools/build-docs-container: guarantee the image to run matches the just-built image
      Makefile: allow to specify build directory

 documentation/.gitignore                 |  1 +
 documentation/Makefile                   | 10 ++--
 documentation/tools/build-docs-container | 90 +++++++++++++++++++++++---------
 3 files changed, 71 insertions(+), 30 deletions(-)
---
base-commit: f9042e1da554017fe46460c1fd2bdf8c74b3fa18
change-id: 20251218-concurrent-safety-e3a1a2394064

[PATCH 1/8] tools/build-docs-container: guarantee the image to run matches the just-built image

[Antonin Godard]

From: Quentin Schulz <quentin.schulz@cherry.de>

We aren't that interested in tags actually, the only thing it brings is
a belief that we are going to run exactly what we just built. The issue
is that this is incorrect.

Indeed, one could simply run the script in parallel for the same image.
Script runtime A will build the image A and tag it X, Script runtime B
will build the image B and tag it X, Script runtime B will run the tag X
(image B), Script runtime A will run the tag X (image B). Note that this
problem exists whether we are building from the same tree concurrently
or from different yocto-docs trees concurrently.
One way to fix this could be to introduce random numbers in the tag so
that it's always unique, but we would be flooding the system with
useless tags.

Instead, we can use the sha of the generated image and run that sha
directly. If it's the same across rebuilds, it'll stay the same. If it's
different, the sha will be different and thus we are safe from
concurrent use.

The only downside is that we cannot infer from the image sha the
underlying distro we're testing.

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 documentation/tools/build-docs-container | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/documentation/tools/build-docs-container b/documentation/tools/build-docs-container
index 23c3dfe33..2f31295ed 100755
--- a/documentation/tools/build-docs-container
+++ b/documentation/tools/build-docs-container
@@ -80,10 +80,6 @@ main ()
 
   OCI=$(which "$CONTAINERCMD")
 
-  # docker build doesn't accept 2 colons, so "sanitize" the name
-  local sanitized_dockername
-  sanitized_dockername=$(echo "$image" | tr ':.' '-')
-
   local version
   version=$(echo "$image" | awk -F: '{print $NF}')
 
@@ -159,8 +155,13 @@ main ()
       ;;
   esac
 
+  local image_sha
+  image_id_file=$(mktemp)
+  # Don't clutter tmpfs on fails
+  trap 'rm -f "$image_id_file"' EXIT
+
   $OCI build \
-    --tag "yocto-docs-$sanitized_dockername:latest" \
+    --iidfile "$image_id_file" \
     --build-arg ARG_FROM="$repo/$image" \
     --build-arg INCLUDE_ESSENTIAL_PACKAGES="${INCLUDE_ESSENTIAL_PACKAGES}" \
     --build-arg ESSENTIAL="host_packages_scripts/$essential" \
@@ -170,6 +171,9 @@ main ()
     --file "$SCRIPT_DIR/containerfiles/$containerfile" \
     "$SCRIPT_DIR"
 
+  image_sha="$(< "$image_id_file")"
+  rm "$image_id_file"
+
   local -a args_run=(
     --rm
     --interactive
@@ -193,7 +197,7 @@ main ()
 
   $OCI run \
     "${args_run[@]}" \
-    "yocto-docs-$sanitized_dockername" \
+    "$image_sha" \
     "$@"
 }
 

-- 
2.51.0

[PATCH 2/8] Makefile: allow to specify build directory

[Antonin Godard]

From: Quentin Schulz <quentin.schulz@cherry.de>

This can be useful to compare the output of two runs or separate the
build directory of 2+ distro builds from tools/build-docs-container.

Note that make clean cannot remove BUILDDIR from previous runs if they
differ as it wouldn't be able to know what it was named in the past.

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 documentation/Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/Makefile b/documentation/Makefile
index e144a50b4..5f84a93e3 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -11,7 +11,7 @@ SOURCEDIR      = .
 VALEDOCS       ?= $(SOURCEDIR)
 SPHINXLINTDOCS ?= $(SOURCEDIR)
 IMAGEDIRS      = */svg
-BUILDDIR       = _build
+BUILDDIR       ?= _build
 DESTDIR        = final
 SVG2PNG        = rsvg-convert
 SVG2PDF        = rsvg-convert

-- 
2.51.0

[PATCH 3/8] tools/build-docs-container: build in separate directory for each distro

[Antonin Godard]

This allows to compare build output from different distros if necessary
and make it easier to make sure we start building from a clean slate.

Co-developed-by: Quentin Schulz <quentin.schulz@cherry.de>
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/tools/build-docs-container | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/documentation/tools/build-docs-container b/documentation/tools/build-docs-container
index 2f31295ed..b377777ed 100755
--- a/documentation/tools/build-docs-container
+++ b/documentation/tools/build-docs-container
@@ -76,6 +76,7 @@ main ()
   fi
 
   local image="$1"
+  local orig_image=$image
   shift
 
   OCI=$(which "$CONTAINERCMD")
@@ -181,6 +182,7 @@ main ()
     --volume="$DOCS_DIR:/docs:rw"
     --workdir=/docs
     --security-opt label=disable
+    --env BUILDDIR="_build/$orig_image-$image_sha"
   )
 
   if [ "$(basename "$OCI")" = "docker" ]; then

-- 
2.51.0

[PATCH 4/8] tools/build-docs-container: create symlink to latest build output

[Antonin Godard]

This is useful to open the output always at the same location.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/tools/build-docs-container | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/documentation/tools/build-docs-container b/documentation/tools/build-docs-container
index b377777ed..7f3ba3680 100755
--- a/documentation/tools/build-docs-container
+++ b/documentation/tools/build-docs-container
@@ -185,6 +185,10 @@ main ()
     --env BUILDDIR="_build/$orig_image-$image_sha"
   )
 
+  # Create a symlink pointing to the latest build output
+  mkdir -p "$DOCS_DIR"/documentation/_build
+  ln -snf "$orig_image-$image_sha" "$DOCS_DIR"/documentation/_build/latest
+
   if [ "$(basename "$OCI")" = "docker" ]; then
     args_run+=(
       --user="$(id -u)":"$(id -g)"

-- 
2.51.0

Re: [PATCH 4/8] tools/build-docs-container: create symlink to latest build output

[Quentin Schulz]

Hi Antonin,

On 12/22/25 1:27 PM, Antonin Godard wrote:
> This is useful to open the output always at the same location.
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>   documentation/tools/build-docs-container | 4 ++++
>   1 file changed, 4 insertions(+)
> 
> diff --git a/documentation/tools/build-docs-container b/documentation/tools/build-docs-container
> index b377777ed..7f3ba3680 100755
> --- a/documentation/tools/build-docs-container
> +++ b/documentation/tools/build-docs-container
> @@ -185,6 +185,10 @@ main ()
>       --env BUILDDIR="_build/$orig_image-$image_sha"
>     )
>   
> +  # Create a symlink pointing to the latest build output
> +  mkdir -p "$DOCS_DIR"/documentation/_build
> +  ln -snf "$orig_image-$image_sha" "$DOCS_DIR"/documentation/_build/latest
> +

But we haven't even built it yet? It should at the very least be *after* 
$OCI run.

I'm actually wondering if we shouldn't have it as last command in the 
Makefile targets instead? Because here you only add the latest symlink 
if we're building via the containers, but we could also run two native 
builds in parallel (well, hopefully at the end of this series :)?) and 
we wouldn't have a "latest" symlink in that case?

Maybe we should do something like

ROOT_BUILDDIR = _build
BUILDDIR ?= dev (Or something else, just not latest)
FULL_BUILDDIR = $(ROOT_BUILDDIR)/$(BUILDDIR)

Replace all BUILDDIR with FULL_BUILDDIR in Makefile.

In all targets calling SPHINXBUILD, add after it:

ln --force --symbolic --no-dereference $(FULL_BUILDDIR) 
$(ROOT_BUILDDIR)/latest

(Not tested)

What do you think?

Cheers,
Quentin

[PATCH 5/8] Makefile: wrap set_versions.py with flock

[Antonin Godard]

The set_versions.py script modified files in the source directory. To
improve concurrent docs builds, wrap the set_versions.py with flock,
with a 30 seconds timeout.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/.gitignore | 1 +
 documentation/Makefile   | 8 ++++----
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/documentation/.gitignore b/documentation/.gitignore
index b23d598054..a5a5efc19c 100644
--- a/documentation/.gitignore
+++ b/documentation/.gitignore
@@ -9,3 +9,4 @@ releases.rst
 */svg/*.pdf
 styles/*
 !styles/config
+set-versions.lock
diff --git a/documentation/Makefile b/documentation/Makefile
index 5f84a93e32..fe49d74cc6 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -50,7 +50,7 @@ PNGs := $(foreach dir, $(IMAGEDIRS), $(patsubst %.svg,%.png,$(wildcard $(SOURCED
 	$(SVG2PNG) --format=png --output=$@ $<
 
 clean:
-	@rm -rf $(BUILDDIR) $(PNGs) $(PDFs) poky.yaml sphinx-static/switchers.js releases.rst
+	@rm -rf $(BUILDDIR) $(PNGs) $(PDFs) poky.yaml sphinx-static/switchers.js releases.rst set-versions.lock
 
 checks:
 	$(SOURCEDIR)/tools/check-glossaries --docs-dir $(SOURCEDIR)
@@ -63,14 +63,14 @@ sphinx-lint:
 	sphinx-lint $(SPHINXLINTDOCS)
 
 epub: $(PNGs)
-	$(SOURCEDIR)/set_versions.py
+	flock -w 30 "$(SOURCEDIR)"/set-versions.lock -c $(SOURCEDIR)/set_versions.py
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 # Note: we need to pass buf_size here (which is also configurable from
 # texmf.cnf), to avoid following error:
 #   Unable to read an entire line---bufsize=200000. Please increase buf_size in texmf.cnf.
 latexpdf: $(PDFs)
-	$(SOURCEDIR)/set_versions.py
+	flock -w 30 "$(SOURCEDIR)"/set-versions.lock -c $(SOURCEDIR)/set_versions.py
 	buf_size=10000000 $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 all: html epub latexpdf
@@ -78,5 +78,5 @@ all: html epub latexpdf
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %:
-	$(SOURCEDIR)/set_versions.py
+	flock -w 30 "$(SOURCEDIR)"/set-versions.lock -c $(SOURCEDIR)/set_versions.py
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

-- 
2.51.0

Re: [docs] [PATCH 5/8] Makefile: wrap set_versions.py with flock

[Quentin Schulz]

Hi Antonin,

On 12/22/25 1:27 PM, Antonin Godard via lists.yoctoproject.org wrote:
> The set_versions.py script modified files in the source directory. To
> improve concurrent docs builds, wrap the set_versions.py with flock,
> with a 30 seconds timeout.
> 

I don't think that's enough.

I can have sphinx-build of build A use poky.yaml, switchers.js, 
releases.rst while set_versions.py from build B (over)write the files, 
ending with corrupted or partial files.

I think we'd need a lock on set_versions.py + sphinx-build run inside a 
subshell, something like the fourth example in the manpage.

(; flock -w 30 9 || exit 1; # ... commands executed under lock ...; ) 
9>/var/lock/mylockfile

Another option (haven't looked up if it's possible) might be to migrate 
set_versions.py into a sphinx plugin such that the plugin is keeping the 
files in DRAM, or writing them to the BUILDDIR directly for consumption.

> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>   documentation/.gitignore | 1 +
>   documentation/Makefile   | 8 ++++----
>   2 files changed, 5 insertions(+), 4 deletions(-)
> 
> diff --git a/documentation/.gitignore b/documentation/.gitignore
> index b23d598054..a5a5efc19c 100644
> --- a/documentation/.gitignore
> +++ b/documentation/.gitignore
> @@ -9,3 +9,4 @@ releases.rst
>   */svg/*.pdf
>   styles/*
>   !styles/config
> +set-versions.lock
> diff --git a/documentation/Makefile b/documentation/Makefile
> index 5f84a93e32..fe49d74cc6 100644
> --- a/documentation/Makefile
> +++ b/documentation/Makefile
> @@ -50,7 +50,7 @@ PNGs := $(foreach dir, $(IMAGEDIRS), $(patsubst %.svg,%.png,$(wildcard $(SOURCED
>   	$(SVG2PNG) --format=png --output=$@ $<
>   
>   clean:
> -	@rm -rf $(BUILDDIR) $(PNGs) $(PDFs) poky.yaml sphinx-static/switchers.js releases.rst
> +	@rm -rf $(BUILDDIR) $(PNGs) $(PDFs) poky.yaml sphinx-static/switchers.js releases.rst set-versions.lock
>   

That would allow us to run

make clean; make html

in parallel and bypass the flock entirely. If the lock is released, it's 
fine to still have the file no? If it's stuck for some reason (someone 
Ctrl+C the build and flock doesn't release the lock?), we can always say 
you need to remove the lock by hand?

Cheers,
Quentin

[PATCH 6/8] tools/build-docs-container: allow running non-interactively

[Antonin Godard]

When running this script from another one, it can be useful to run the
OCI run command non-interactively, especially when running concurrent
builds. Add a RUN_NON_INTERACIVE env variable that can be set to 1 to
remove the --interactive and --tty options from the run command.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/tools/build-docs-container | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/documentation/tools/build-docs-container b/documentation/tools/build-docs-container
index 7f3ba3680..7a5191710 100755
--- a/documentation/tools/build-docs-container
+++ b/documentation/tools/build-docs-container
@@ -24,6 +24,7 @@ SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &>/dev/null && pwd)
 CONTAINERCMD=${CONTAINERCMD:-docker}
 DOCS_DIR="$SCRIPT_DIR/../.."
 INCLUDE_ESSENTIAL_PACKAGES=${INCLUDE_ESSENTIAL_PACKAGES:-0}
+RUN_NON_INTERACTIVE="${RUN_NON_INTERACTIVE:-0}"
 
 function usage()
 {
@@ -65,6 +66,9 @@ $0 OCI_IMAGE [make arguments...]
      packages listed in documentation/tools/host_packages_scripts/*_essential.sh.
      This is not required to build the documentation but can be useful to validate
      the installation of packages listed in these files (default: 0).
+
+   - RUN_NON_INTERACTIVE: when set to 1, allow the '\$OCI run' command to be run
+     non-interactively, without a tty.
 "
 }
 
@@ -177,14 +181,19 @@ main ()
 
   local -a args_run=(
     --rm
-    --interactive
-    --tty
     --volume="$DOCS_DIR:/docs:rw"
     --workdir=/docs
     --security-opt label=disable
     --env BUILDDIR="_build/$orig_image-$image_sha"
   )
 
+  if [ "${RUN_NON_INTERACTIVE}" != "1" ]; then
+    args_run+=(
+      --interactive
+      --tty
+    )
+  fi
+
   # Create a symlink pointing to the latest build output
   mkdir -p "$DOCS_DIR"/documentation/_build
   ln -snf "$orig_image-$image_sha" "$DOCS_DIR"/documentation/_build/latest

-- 
2.51.0

Re: [PATCH 6/8] tools/build-docs-container: allow running non-interactively

[Quentin Schulz]

Hi Antonin,

On 12/22/25 1:27 PM, Antonin Godard wrote:
> When running this script from another one, it can be useful to run the
> OCI run command non-interactively, especially when running concurrent
> builds. Add a RUN_NON_INTERACIVE env variable that can be set to 1 to
> remove the --interactive and --tty options from the run command.
> 

I don't understand the use-case? Can you provide one?

Also, if you run without -it, do we need to pass other flags inside the 
container? e.g. DEBIAN_FRONTEND=noninteractive for apt-get (I think 
iperf3 prompts the user when installing on debian, so that could be used 
to test).

Cheers,
Quentin

[PATCH 7/8] tools/build-docs-container: allow passing extra args to $OCI run

[Antonin Godard]

Add a OCI_RUN_EXTRA_ARGS env variable to allow customizing the arguments
passed to the podman/docker run command. For example:

  export OCI_RUN_EXTRA_ARGS="--env=SPHINXOPTS=-W --keep-going -j1"

To limit the number of threads used by Sphinx. This is especially useful
for parallel builds.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/tools/build-docs-container | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/documentation/tools/build-docs-container b/documentation/tools/build-docs-container
index 7a5191710..c5cdd9c4c 100755
--- a/documentation/tools/build-docs-container
+++ b/documentation/tools/build-docs-container
@@ -25,6 +25,7 @@ CONTAINERCMD=${CONTAINERCMD:-docker}
 DOCS_DIR="$SCRIPT_DIR/../.."
 INCLUDE_ESSENTIAL_PACKAGES=${INCLUDE_ESSENTIAL_PACKAGES:-0}
 RUN_NON_INTERACTIVE="${RUN_NON_INTERACTIVE:-0}"
+OCI_RUN_EXTRA_ARGS="${OCI_RUN_EXTRA_ARGS:-}"
 
 function usage()
 {
@@ -69,6 +70,8 @@ $0 OCI_IMAGE [make arguments...]
 
    - RUN_NON_INTERACTIVE: when set to 1, allow the '\$OCI run' command to be run
      non-interactively, without a tty.
+
+   - OCI_RUN_EXTRA_ARGS: extra arguments to pass to the '\$OCI run' command.
 "
 }
 
@@ -210,6 +213,9 @@ main ()
     )
   fi
 
+  # Extra arguments.
+  [ -n "$OCI_RUN_EXTRA_ARGS" ] && args_run+=( "${OCI_RUN_EXTRA_ARGS}" )
+
   $OCI run \
     "${args_run[@]}" \
     "$image_sha" \

-- 
2.51.0

Re: [PATCH 7/8] tools/build-docs-container: allow passing extra args to $OCI run

[Quentin Schulz]

Hi Antonin,

On 12/22/25 1:27 PM, Antonin Godard wrote:
> Add a OCI_RUN_EXTRA_ARGS env variable to allow customizing the arguments
> passed to the podman/docker run command. For example:
> 
>    export OCI_RUN_EXTRA_ARGS="--env=SPHINXOPTS=-W --keep-going -j1"
> 
> To limit the number of threads used by Sphinx. This is especially useful
> for parallel builds.
> 

How about exporting host variables inside the container? That would 
allow to not have to add OCI_RUN_EXTRA_ARGS when comparing native with 
container's output.

Something like

args_run+=(--env SPHINXOPTS)
args_run+=(--env SPHINXBUILD)
args_run+=(--env VALEOPTS)
args_run+=(--env VALEDOCS)
args_run+=(--env SPHINXLINTDOCS)

(not tested).

Also, you can already do that by simply doing

documentation/tools/build-docs-container leap:15.6 SPHINXOPTS=--bla html

for example.

FYI, I've realized that our "which CONTAINERCMD" doesn't actually work 
when you have podman-docker installed. I had an alias in my zshrc 
setting docker to podman directly... I need to figure out if there's a 
way to detect whether podman-docker is installed and in that case use 
podman instead of docker. The user mapping doesn't seem to work though 
(using the docker configuration in our script, with podman-docker 
installed, so effectively using rootless podman but with docker 
arguments). Seems like the owner of files within the container is not 
mapped to a host container (all owned by root in the container, which 
seems to be the default when a user id doesn't map to anything known on 
the host).

/usr/bin/docker is a shell script exec'ing podman with the same args but 
the naive check on whether it's a shell script is probably a bad idea, 
as nothing guarantees it is a shell script on all distros or that docker 
won't suddenly become a shell script itself.

Cheers,
Quentin

[PATCH 8/8] tools/build-docs-container: make it possible to print the distro list

[Antonin Godard]

Add a special "supported_distros" argument to the script to make it
possible to return the list of supported distros. This is useful for use
in a external script, to run the docs build on a specific set or all
supported distros concurrently.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/tools/build-docs-container | 49 +++++++++++++++++++++-----------
 1 file changed, 32 insertions(+), 17 deletions(-)

diff --git a/documentation/tools/build-docs-container b/documentation/tools/build-docs-container
index c5cdd9c4c..510435c3c 100755
--- a/documentation/tools/build-docs-container
+++ b/documentation/tools/build-docs-container
@@ -20,6 +20,32 @@
 
 set -eu -o pipefail
 
+declare -a _SUPPORTED_DISTROS=(
+  almalinux:8
+  almalinux:9
+  centos:stream9
+  debian:12
+  debian:13
+  fedora:39
+  fedora:40
+  fedora:41
+  fedora:42
+  leap:15.5
+  leap:15.6
+  rockylinux:8
+  rockylinux:9
+  ubuntu:22.04
+  ubuntu:24.04
+  ubuntu:25.04
+  ubuntu:25.10
+)
+
+
+if [ "${1:-}" = "supported_distros" ]; then
+  echo "${_SUPPORTED_DISTROS[@]}"
+  exit 0
+fi
+
 SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &>/dev/null && pwd)
 CONTAINERCMD=${CONTAINERCMD:-docker}
 DOCS_DIR="$SCRIPT_DIR/../.."
@@ -35,24 +61,13 @@ $0 OCI_IMAGE [make arguments...]
 
    OCI_IMAGE is an image:tag of an OCI image hosted on hub.docker.com. It is one
    of:
-     - almalinux:8
-     - almalinux:9
-     - centos:stream9
-     - debian:12
-     - debian:13
-     - fedora:39
-     - fedora:40
-     - fedora:41
-     - fedora:42
-     - leap:15.5
-     - leap:15.6
-     - rockylinux:8
-     - rockylinux:9
-     - ubuntu:22.04
-     - ubuntu:24.04
-     - ubuntu:25.04
-     - ubuntu:25.10
+"
+
+  for distro in "${_SUPPORTED_DISTROS[@]}"; do
+    echo "   - $distro"
+  done
 
+  echo "
    [make arguments] is one or more argument to pass to the make command of
    documentation/Makefile, see that file for what's supported. This is typically
    intended to be used to provide specific make targets.

-- 
2.51.0

Re: [PATCH 8/8] tools/build-docs-container: make it possible to print the distro list

[Quentin Schulz]

Hi Antonin,

On 12/22/25 1:27 PM, Antonin Godard wrote:
> Add a special "supported_distros" argument to the script to make it
> possible to return the list of supported distros. This is useful for use
> in a external script, to run the docs build on a specific set or all
> supported distros concurrently.
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>   documentation/tools/build-docs-container | 49 +++++++++++++++++++++-----------
>   1 file changed, 32 insertions(+), 17 deletions(-)
> 
> diff --git a/documentation/tools/build-docs-container b/documentation/tools/build-docs-container
> index c5cdd9c4c..510435c3c 100755
> --- a/documentation/tools/build-docs-container
> +++ b/documentation/tools/build-docs-container
> @@ -20,6 +20,32 @@
>   
>   set -eu -o pipefail
>   
> +declare -a _SUPPORTED_DISTROS=(
> +  almalinux:8
> +  almalinux:9
> +  centos:stream9
> +  debian:12
> +  debian:13
> +  fedora:39
> +  fedora:40
> +  fedora:41
> +  fedora:42
> +  leap:15.5
> +  leap:15.6
> +  rockylinux:8
> +  rockylinux:9
> +  ubuntu:22.04
> +  ubuntu:24.04
> +  ubuntu:25.04
> +  ubuntu:25.10
> +)
> +
> +
> +if [ "${1:-}" = "supported_distros" ]; then
> +  echo "${_SUPPORTED_DISTROS[@]}"
> +  exit 0
> +fi
> +
>   SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &>/dev/null && pwd)
>   CONTAINERCMD=${CONTAINERCMD:-docker}
>   DOCS_DIR="$SCRIPT_DIR/../.."
> @@ -35,24 +61,13 @@ $0 OCI_IMAGE [make arguments...]
>   
>      OCI_IMAGE is an image:tag of an OCI image hosted on hub.docker.com. It is one

Oopsies, centos:stream9 is not on hub.docker.com!

>      of:
> -     - almalinux:8
> -     - almalinux:9
> -     - centos:stream9
> -     - debian:12
> -     - debian:13
> -     - fedora:39
> -     - fedora:40
> -     - fedora:41
> -     - fedora:42
> -     - leap:15.5
> -     - leap:15.6
> -     - rockylinux:8
> -     - rockylinux:9
> -     - ubuntu:22.04
> -     - ubuntu:24.04
> -     - ubuntu:25.04
> -     - ubuntu:25.10
> +"
> +
> +  for distro in "${_SUPPORTED_DISTROS[@]}"; do
> +    echo "   - $distro"
> +  done
>   
> +  echo "

No need to cut the usage string in two, you can call subshells directly 
in it, e.g.:

echo "test

$(for distro in "${_SUPPORTED_DISTROS[@]}"; do
     echo "   - $distro"
done)

testestest"

Should work just fine.

No need to change it, just wanted to highlight there's also another way 
of doing it :)

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
Tested-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

Re: [PATCH 0/8] Parallel docs build improvements

[Quentin Schulz]

Hi Antonin,

On 12/22/25 1:27 PM, Antonin Godard wrote:
> The aim of this series is to take the work of Quentin[1] and with
> additional commit that improve the concurrent safety of the docs build,
> and some general improvements to the build-docs-container script.
> 
> This allows building the docs on all supported distros with this bash
> snippet:
> 
> ```
> declare -a distros=( $(./documentation/tools/build-docs-container supported_distros) )
> 
> for distro in "${distros[@]}"; do
>    ./documentation/tools/build-docs-container $distro "$target" >/tmp/docs-build-"$distro".log 2>&1 &
> done
> 
> wait
> ```
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
> Antonin Godard (6):
>        tools/build-docs-container: build in separate directory for each distro
>        tools/build-docs-container: create symlink to latest build output
>        Makefile: wrap set_versions.py with flock
>        tools/build-docs-container: allow running non-interactively
>        tools/build-docs-container: allow passing extra args to $OCI run
>        tools/build-docs-container: make it possible to print the distro list
> 
> Quentin Schulz (2):
>        tools/build-docs-container: guarantee the image to run matches the just-built image
>        Makefile: allow to specify build directory
> 

Those are not following (kernel) contribution requirements.

See 
https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin

Anyone who *sends* a patch need to add their SoB (at the end of the list 
of SoBs, Rbs, etc...) even if they are not the author (who needs to be 
the "first" SoB; see exceptions in the Co-developed-by: section 
underneath the section I linked just above (I don't understand the 
exceptions but I rarely have to add Co-developed-by so it's not been an 
issue for me so far)).

We don't document this in 
https://docs.yoctoproject.org/contributor-guide/submit-changes.html 
(possibly because people rarely take over patches in Yocto?).

Cheers,
Quentin