21 files changed, 280 insertions, 0 deletions

diff --git a/documentation/tools/Containerfile.almalinux b/documentation/tools/Containerfile.almalinux
new file mode 120000
index 0000000000..7237e9b99f
--- /dev/null
+++ b/documentation/tools/Containerfile.almalinux
@@ -0,0 +1 @@
+Containerfile.dnf
\ No newline at end of file
diff --git a/documentation/tools/Containerfile.apt b/documentation/tools/Containerfile.apt
new file mode 100644
index 0000000000..5e30b65eb8
--- /dev/null
+++ b/documentation/tools/Containerfile.apt
@@ -0,0 +1,26 @@
+ARG ARG_FROM=debian:12 # default value to avoid warning
+FROM $ARG_FROM
+
+ARG DOCS=ubuntu_docs.sh
+ARG DOCS_PDF=ubuntu_docs_pdf.sh
+
+ENV DEBIAN_FRONTEND=noninteractive
+ARG TZ=Europe/Vienna
+
+# relative to the location of the dockerfile
+COPY --chmod=777 ${DOCS} /temp/host_packages_docs.sh
+COPY --chmod=777 ${DOCS_PDF} /temp/host_packages_docs_pdf.sh
+
+RUN ln -fs "/usr/share/zoneinfo/$TZ" /etc/localtime \
+ && apt-get update \
+ && apt-get install -y sudo \
+ && yes | /temp/host_packages_docs.sh \
+ && yes | /temp/host_packages_docs_pdf.sh \
+ && apt-get --yes autoremove \
+ && apt-get clean \
+ && rm -rf /temp
+
+RUN git config --global --add safe.directory /docs
+
+ENTRYPOINT ["/usr/bin/env", "make", "-C", "documentation/"]
+CMD ["publish"]
diff --git a/documentation/tools/Containerfile.debian b/documentation/tools/Containerfile.debian
new file mode 120000
index 0000000000..5a7a425197
--- /dev/null
+++ b/documentation/tools/Containerfile.debian
@@ -0,0 +1 @@
+Containerfile.apt
\ No newline at end of file
diff --git a/documentation/tools/Containerfile.dnf b/documentation/tools/Containerfile.dnf
new file mode 100644
index 0000000000..3dae744455
--- /dev/null
+++ b/documentation/tools/Containerfile.dnf
@@ -0,0 +1,25 @@
+ARG ARG_FROM=fedora:40 # default value to avoid warning
+FROM $ARG_FROM
+
+ARG DOCS=fedora_docs.sh
+ARG DOCS_PDF=fedora_docs_pdf.sh
+ARG PIP3=pip3_docs.sh
+
+# relative to the location of the dockerfile
+COPY --chmod=777 ${DOCS} /temp/host_packages_docs.sh
+COPY --chmod=777 ${DOCS_PDF} /temp/host_packages_docs_pdf.sh
+COPY --chmod=777 ${PIP3} /temp/pip3_docs.sh
+
+RUN dnf update -y \
+ && dnf install -y sudo \
+ && yes | /temp/host_packages_docs.sh \
+ && yes | /temp/host_packages_docs_pdf.sh \
+ && yes | /temp/pip3_docs.sh \
+ && dnf autoremove -y \
+ && dnf clean all -y \
+ && rm -rf /temp
+
+RUN git config --global --add safe.directory /docs
+
+ENTRYPOINT ["/usr/bin/env", "make", "-C", "documentation/"]
+CMD ["publish"]
diff --git a/documentation/tools/Containerfile.fedora b/documentation/tools/Containerfile.fedora
new file mode 120000
index 0000000000..7237e9b99f
--- /dev/null
+++ b/documentation/tools/Containerfile.fedora
@@ -0,0 +1 @@
+Containerfile.dnf
\ No newline at end of file
diff --git a/documentation/tools/Containerfile.ubuntu b/documentation/tools/Containerfile.ubuntu
new file mode 120000
index 0000000000..5a7a425197
--- /dev/null
+++ b/documentation/tools/Containerfile.ubuntu
@@ -0,0 +1 @@
+Containerfile.apt
\ No newline at end of file
diff --git a/documentation/tools/Containerfile.zypper b/documentation/tools/Containerfile.zypper
new file mode 100644
index 0000000000..f27ad1b476
--- /dev/null
+++ b/documentation/tools/Containerfile.zypper
@@ -0,0 +1,32 @@
+ARG ARG_FROM=opensuse/leap:15.4 # default value to avoid warning
+FROM $ARG_FROM
+
+ARG DOCS=opensuse_docs.sh
+ARG DOCS_PDF=opensuse_docs_pdf.sh
+ARG PIP3=pip3_docs.sh
+
+# relative to the location of the dockerfile
+COPY --chmod=777 ${DOCS} /temp/host_packages_docs.sh
+COPY --chmod=777 ${DOCS_PDF} /temp/host_packages_docs_pdf.sh
+COPY --chmod=777 ${PIP3} /temp/pip3_docs.sh
+
+# Zypper doesn't have environment variables to specify whether to run in
+# non-interactive mode like Debian does with DEBIAN_FRONTEND and piping yes to
+# the scripts doesn't need to be enough as well, so let's force all zypper calls
+# to be non-interactive by adding the appropriate flag in the scripts.
+RUN for script in /temp/*.sh; do \
+        sed -i 's/zypper/zypper --non-interactive/' $script; \
+    done
+
+RUN zypper update -y \
+ && zypper install -y sudo \
+ && yes | /temp/host_packages_docs.sh \
+ && yes | /temp/host_packages_docs_pdf.sh \
+ && yes | /temp/pip3_docs.sh \
+ && zypper clean --all \
+ && rm -rf /temp
+
+RUN git config --global --add safe.directory /docs
+
+ENTRYPOINT ["/usr/bin/env", "make", "-C", "documentation/"]
+CMD ["publish"]
diff --git a/documentation/tools/build-docs-container b/documentation/tools/build-docs-container
new file mode 100755
index 0000000000..6b4d425434
--- /dev/null
+++ b/documentation/tools/build-docs-container
@@ -0,0 +1,175 @@
+#!/usr/bin/env bash
+# -*- vim: set expandtab tabstop=2 shiftwidth=2:
+#
+# Build a container ready to build the documentation be reading the dependencies
+# listed in shell scripts in documentation/tools/host_packages_scripts, and
+# start a documentation build in this container.
+#
+# Usage:
+#
+#   ./documentation/tools/build-docs-container <image> [<make target>]
+#
+# e.g.:
+#
+#   ./documentation/tools/build-docs-container ubuntu:24.04 html
+#
+# Will build the docs in an Ubuntu 24.04 container in html.
+#
+# The container engine can be selected by exporting CONTAINERCMD in the
+# environment. The default is docker, but podman can also be used.
+
+set -eu -o pipefail
+
+SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &>/dev/null && pwd)
+CONTAINERCMD=${CONTAINERCMD:-docker}
+DOCS_DIR="$SCRIPT_DIR/../.."
+SH_DIR="$SCRIPT_DIR/host_packages_scripts"
+
+function usage()
+{
+  echo "$0 -- script to build documentation from within a container
+
+$0 OCI_IMAGE [make arguments...]
+
+   OCI_IMAGE is an image:tag of an OCI image hosted on hub.docker.com. It is one
+   of:
+     - debian:12
+     - fedora:38
+     - fedora:39
+     - fedora:40
+     - leap:15.4
+     - leap:15.5
+     - ubuntu:22.04
+     - ubuntu:24.04
+
+   [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.
+   Default: publish
+"
+}
+
+main ()
+{
+  if [ "$#" -lt 1 ]; then
+    usage
+    exit 1
+  fi
+
+  local image="$1"
+  shift
+
+  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}')
+
+  case $image in
+    # Missing latexmk texlive-gnu-freefont packages at the very least
+    # "almalinux:8"*|\
+    # "almalinux:9"*)
+    #   containerfile=Containerfile.almalinux
+    #   docs=almalinux_docs.sh
+    #   docs_pdf=almalinux_docs_pdf.sh
+    #   pip3=pip3_docs.sh
+    #   ;;
+    # Missing python3-saneyaml
+    # "debian:11"*|\
+    "debian:12"*)
+      containerfile=Containerfile.debian
+      docs=ubuntu_docs.sh
+      docs_pdf=ubuntu_docs_pdf.sh
+      ;;
+    "fedora:38"*|\
+    "fedora:39"*|\
+    "fedora:40"*)
+      containerfile=Containerfile.fedora
+      docs=fedora_docs.sh
+      docs_pdf=fedora_docs_pdf.sh
+      pip3=pip3_docs.sh
+      ;;
+    "leap:15.4"*|\
+    "leap:15.5"*)
+    # Seems like issue with permissions package, c.f.
+    #
+    # Updating /etc/sysconfig/security ...
+    # /dev/zero: chown: Permission denied
+    # /dev/null: chown: Permission denied
+    # /dev/full: chown: Permission denied
+    # ERROR: not all operations were successful.
+    # Checking permissions and ownerships - using the permissions files
+    #   /etc/permissions
+    #   /etc/permissions.easy
+    #   /etc/permissions.local
+    # setting / to root:root 0755. (wrong permissions 0555)
+    # setting /dev/zero to root:root 0666. (wrong owner/group 65534:65534)
+    # setting /dev/null to root:root 0666. (wrong owner/group 65534:65534)
+    # setting /dev/full to root:root 0666. (wrong owner/group 65534:65534)
+    # warning: %post(permissions-20240826-150600.10.12.1.x86_64) scriptlet failed, exit status 1
+    #
+    # "leap:15.6"*)
+      image=opensuse/leap:$version
+      containerfile=Containerfile.zypper
+      docs=opensuse_docs.sh
+      docs_pdf=opensuse_docs_pdf.sh
+      pip3=pip3_docs.sh
+      ;;
+    # Missing python3-saneyaml
+    # "ubuntu:18.04"*|\
+    # "ubuntu:20.04"*|\
+    # Cannot fetch packages anymore
+    # "ubuntu:23.04"*|\
+    "ubuntu:22.04"*|\
+    "ubuntu:24.04"*)
+      containerfile=Containerfile.ubuntu
+      docs=ubuntu_docs.sh
+      docs_pdf=ubuntu_docs_pdf.sh
+      ;;
+    *)
+      echo "$image not supported!"
+      usage
+      exit 1
+      ;;
+  esac
+
+  $OCI build \
+    --tag "yocto-docs-$sanitized_dockername:latest" \
+    --build-arg ARG_FROM="docker.io/$image" \
+    --build-arg DOCS="$docs" \
+    --build-arg DOCS_PDF="$docs_pdf" \
+    --build-arg PIP3="${pip3:-}" \
+    --file "$SCRIPT_DIR/$containerfile" \
+    "$SH_DIR/"
+
+  local -a args_run=(
+    --rm
+    --interactive
+    --tty
+    --volume="$DOCS_DIR:/docs:rw"
+    --workdir=/docs
+    --security-opt label=disable
+  )
+
+  if [ "$OCI" = "docker" ]; then
+    args_run+=(
+      --user="$(id -u)":"$(id -g)"
+    )
+  elif [ "$OCI" = "podman" ]; then
+    # we need net access to fetch bitbake terms
+    args_run+=(
+      --cap-add=NET_RAW
+      --userns=keep-id
+    )
+  fi
+
+  $OCI run \
+    "${args_run[@]}" \
+    "yocto-docs-$sanitized_dockername" \
+    "$@"
+}
+
+main "$@"
diff --git a/documentation/tools/host_packages_scripts/almalinux_docs.sh b/documentation/tools/host_packages_scripts/almalinux_docs.sh
new file mode 100644
index 0000000000..8188d529a1
--- /dev/null
+++ b/documentation/tools/host_packages_scripts/almalinux_docs.sh
@@ -0,0 +1 @@
+sudo dnf install git glibc-locale-source librsvg2-tools make python3-pip which
diff --git a/documentation/tools/host_packages_scripts/almalinux_docs_pdf.sh b/documentation/tools/host_packages_scripts/almalinux_docs_pdf.sh
new file mode 100644
index 0000000000..8341eb8c25
--- /dev/null
+++ b/documentation/tools/host_packages_scripts/almalinux_docs_pdf.sh
@@ -0,0 +1 @@
+sudo dnf install latexmk texlive-collection-fontsrecommended texlive-collection-latex texlive-collection-latexrecommended texlive-collection-xetex texlive-fncychap texlive-gnu-freefont texlive-tex-gyre texlive-xetex
diff --git a/documentation/tools/host_packages_scripts/almalinux_essential.sh b/documentation/tools/host_packages_scripts/almalinux_essential.sh
new file mode 100644
index 0000000000..76c5280eeb
--- /dev/null
+++ b/documentation/tools/host_packages_scripts/almalinux_essential.sh
@@ -0,0 +1,5 @@
+sudo dnf install -y epel-release
+sudo yum install dnf-plugins-core
+sudo dnf config-manager --set-enabled crb
+sudo dnf makecache
+sudo dnf install bzip2 ccache chrpath cpio cpp diffstat diffutils gawk gcc gcc-c++ git glibc-devel glibc-langpack-en gzip libacl make patch perl perl-Data-Dumper perl-Text-ParseWords perl-Thread-Queue python3 python3-GitPython python3-jinja2 python3-pexpect python3-pip rpcgen socat tar texinfo unzip wget which xz zstd
diff --git a/documentation/tools/host_packages_scripts/fedora_docs.sh b/documentation/tools/host_packages_scripts/fedora_docs.sh
new file mode 100644
index 0000000000..8188d529a1
--- /dev/null
+++ b/documentation/tools/host_packages_scripts/fedora_docs.sh
@@ -0,0 +1 @@
+sudo dnf install git glibc-locale-source librsvg2-tools make python3-pip which
diff --git a/documentation/tools/host_packages_scripts/fedora_docs_pdf.sh b/documentation/tools/host_packages_scripts/fedora_docs_pdf.sh
new file mode 100644
index 0000000000..816f1c36ec
--- /dev/null
+++ b/documentation/tools/host_packages_scripts/fedora_docs_pdf.sh
@@ -0,0 +1 @@
+sudo dnf install 'texlive-collection-lang*' latexmk texlive-collection-fontsextra texlive-collection-fontsrecommended texlive-collection-latex texlive-collection-latexextra texlive-collection-latexrecommended texlive-collection-xetex texlive-fncychap texlive-gnu-freefont texlive-tex-gyre texlive-xetex
diff --git a/documentation/tools/host_packages_scripts/fedora_essential.sh b/documentation/tools/host_packages_scripts/fedora_essential.sh
new file mode 100644
index 0000000000..ea14134398
--- /dev/null
+++ b/documentation/tools/host_packages_scripts/fedora_essential.sh
@@ -0,0 +1 @@
+sudo dnf install bzip2 ccache chrpath cpio cpp diffstat diffutils file findutils gawk gcc gcc-c++ git glibc-devel glibc-langpack-en gzip hostname libacl make patch perl perl-Data-Dumper perl-File-Compare perl-File-Copy perl-FindBin perl-Text-ParseWords perl-Thread-Queue perl-bignum perl-locale python python3 python3-GitPython python3-jinja2 python3-pexpect python3-pip rpcgen socat tar texinfo unzip wget which xz zstd
diff --git a/documentation/tools/host_packages_scripts/opensuse_docs.sh b/documentation/tools/host_packages_scripts/opensuse_docs.sh
new file mode 100644
index 0000000000..7d36eb0f99
--- /dev/null
+++ b/documentation/tools/host_packages_scripts/opensuse_docs.sh
@@ -0,0 +1 @@
+sudo zypper install git glibc-i18ndata make python3-pip rsvg-convert which
diff --git a/documentation/tools/host_packages_scripts/opensuse_docs_pdf.sh b/documentation/tools/host_packages_scripts/opensuse_docs_pdf.sh
new file mode 100644
index 0000000000..ee9f07886c
--- /dev/null
+++ b/documentation/tools/host_packages_scripts/opensuse_docs_pdf.sh
@@ -0,0 +1 @@
+sudo zypper install 'texlive-collection-lang*' texlive-collection-fontsextra texlive-collection-fontsrecommended texlive-collection-latex texlive-collection-latexextra texlive-collection-latexrecommended texlive-collection-xetex texlive-fncychap texlive-gnu-freefont texlive-latexmk texlive-tex-gyre texlive-xetex
diff --git a/documentation/tools/host_packages_scripts/opensuse_essential.sh b/documentation/tools/host_packages_scripts/opensuse_essential.sh
new file mode 100644
index 0000000000..0d37e9bd5a
--- /dev/null
+++ b/documentation/tools/host_packages_scripts/opensuse_essential.sh
@@ -0,0 +1,2 @@
+sudo zypper install bzip2 chrpath diffstat gcc gcc-c++ git gzip hostname libacl1 make makeinfo patch python python-curses python-xml python3 python3-Jinja2 python3-curses python3-pexpect python3-pip rpcgen socat tar wget which xz zstd
+sudo pip3 install GitPython
diff --git a/documentation/tools/host_packages_scripts/pip3_docs.sh b/documentation/tools/host_packages_scripts/pip3_docs.sh
new file mode 100644
index 0000000000..fd6ad98053
--- /dev/null
+++ b/documentation/tools/host_packages_scripts/pip3_docs.sh
@@ -0,0 +1 @@
+sudo pip3 install sphinx sphinx_rtd_theme pyyaml
diff --git a/documentation/tools/host_packages_scripts/ubuntu_docs.sh b/documentation/tools/host_packages_scripts/ubuntu_docs.sh
new file mode 100644
index 0000000000..d2a1832e27
--- /dev/null
+++ b/documentation/tools/host_packages_scripts/ubuntu_docs.sh
@@ -0,0 +1 @@
+sudo apt install git librsvg2-bin locales make python3-saneyaml python3-saneyaml python3-sphinx-rtd-theme sphinx
diff --git a/documentation/tools/host_packages_scripts/ubuntu_docs_pdf.sh b/documentation/tools/host_packages_scripts/ubuntu_docs_pdf.sh
new file mode 100644
index 0000000000..d6310bd21d
--- /dev/null
+++ b/documentation/tools/host_packages_scripts/ubuntu_docs_pdf.sh
@@ -0,0 +1 @@
+sudo apt install fonts-freefont-otf latexmk tex-gyre texlive-fonts-extra texlive-fonts-recommended texlive-lang-all texlive-latex-extra texlive-latex-recommended texlive-xetex
diff --git a/documentation/tools/host_packages_scripts/ubuntu_essential.sh b/documentation/tools/host_packages_scripts/ubuntu_essential.sh
new file mode 100644
index 0000000000..6584a0403d
--- /dev/null
+++ b/documentation/tools/host_packages_scripts/ubuntu_essential.sh
@@ -0,0 +1 @@
+sudo apt-get install build-essential chrpath cpio debianutils diffstat file gawk gcc git iputils-ping libacl1 locales python3 python3-git python3-jinja2 python3-pexpect python3-pip python3-subunit socat texinfo unzip wget xz-utils zstd