[v2,0/3] tools/build-docs-container: improve concurrent safety

Currently, it is possible to run the script from two different trees and
ending up running the wrong image due to the non-uniqueness of our tags.

Indeed, one could simply run the script in parallel for the same distro.
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.
This fixes the issue by using the iid-file generated by podman build
containing the sha of the just-built image as "image" argument to
podman run, guaranteeing we are using the image we just built.

This also now forces builds triggered by tools/build-docs-container to
build in separate directories. This helps comparing the output between
different runs as well as making sure we aren't reusing the build
directory from another run by mistake. The downside is that it can
clutter your local tree and make clean is not able to clean previous
runs because it cannot know which build directory you picked in earlier
runs.

set_versions.py still modifies the tree so this probably means we aren't
concurrent-safe from the same tree because of that. But we should now be
safe running tools/build-docs-container from separate trees.

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
Changes in v2:
- made image_id_file a global variable so the trap can use the variable,
- added patch to customize BUILDDIR,
- added patch to set BUILDDIR uniquely per run of
  tools/build-docs-container,
- Link to v1: https://lore.kernel.org/r/20251009-iid-file-v1-1-d9ca8563c88c@cherry.de

---
Quentin Schulz (3):
      tools/build-docs-container: guarantee the image to run matches the just-built image
      Makefile: allow to specify build directory
      tools/build-docs-container: build in separate directory for each distro

 documentation/Makefile                   |  2 +-
 documentation/tools/build-docs-container | 18 ++++++++++++------
 2 files changed, 13 insertions(+), 7 deletions(-)
---
base-commit: 09c7800333b17b21e50d2a089a3ae1b123697243
change-id: 20251009-iid-file-f276784e0425

Best regards,