From 835eadcaa98bcf8248f372804ebfcfa62677e199 Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Wed, 10 Jun 2026 20:14:31 +0100 Subject: [PATCH 1/6] docs: Drop orphaned blockdiag extension blockdiag is orphaned upstream, incompatible with pillow>=10, and uses APIs removed from modern setuptools (pkg_resources). It forced the pillow<10 / setuptools<81 pins that block building the docs on current Python (3.13+), see thesofproject/sof-docs#472. It was used for a single diagram. Convert that diagram (mpp_layer EDF scheduling example) to graphviz, which is already a dependency and renders the rest of the diagrams, then remove the blockdiag extension and the pillow<10 pin from both requirements files. With this change the documentation builds on current Python with no version ceilings. Co-Authored-By: Claude Opus 4.8 (1M context) Signed-off-by: Liam Girdwood --- .../images/mpp_scheduling/edf_scheduling.diag | 42 ------------------- .../images/mpp_scheduling/edf_scheduling.dot | 23 ++++++++++ .../sof-zephyr/mpp_layer/mpp_scheduling.rst | 2 +- conf.py | 4 +- scripts/requirements-lax.txt | 6 --- scripts/requirements.txt | 6 --- 6 files changed, 25 insertions(+), 58 deletions(-) delete mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/edf_scheduling.diag create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/edf_scheduling.dot diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/edf_scheduling.diag b/architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/edf_scheduling.diag deleted file mode 100644 index b9680b22..00000000 --- a/architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/edf_scheduling.diag +++ /dev/null @@ -1,42 +0,0 @@ -// FIXME: blockdiag is orphaned and not compatible with Pillow anymore: -// https://github.com/blockdiag/blockdiag/pull/171 - -blockdiag edf_scheduling { - - node_width = 250; - node_height = 120; - default_fontsize = 16; - - Comp_1 -> Comp_2 - comment_1 -> Comp_2 [style=dashed] - Comp_2 -> Comp_3 - comment_2 -> Comp_3 [style=dashed] - Comp_3 -> Comp_4 - comment_3 -> Comp_4 [style=dashed] - Comp_4 -> sink - comment_4 -> sink [style=dashed] - - Comp_1 [label="DP component 1\n - *processing period\n - *compute requirement"] - Comp_2 [label="DP component 2\n - *processing period\n - *compute requirement"] - Comp_3 [label="DP component 3\n - *processing period\n - *compute requirement"] - Comp_4 [label="DP component 4\n - *processing period\n - *compute requirement"] - - sink [label="real time sink", shape=endpoint, fontsize = 16] - - comment_1 [label="DP1 to deliver data let\n - DP2 meet its objective"] - comment_2 [label="DP2 to deliver data let\n - DP3 meet its objective"] - comment_3 [label="DP3 to deliver data let\n - DP4 meet its objective"] - comment_4 [label="DP4 to deliver data\n - to real time-sink"] -} diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/edf_scheduling.dot b/architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/edf_scheduling.dot new file mode 100644 index 00000000..91447f91 --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/edf_scheduling.dot @@ -0,0 +1,23 @@ +digraph edf_scheduling { + rankdir = LR; + node [shape = box, fontsize = 12]; + + Comp_1 [label = "DP component 1\n* processing period\n* compute requirement"]; + Comp_2 [label = "DP component 2\n* processing period\n* compute requirement"]; + Comp_3 [label = "DP component 3\n* processing period\n* compute requirement"]; + Comp_4 [label = "DP component 4\n* processing period\n* compute requirement"]; + + sink [label = "real time sink", shape = doublecircle]; + + comment_1 [label = "DP1 to deliver data let\nDP2 meet its objective", shape = note]; + comment_2 [label = "DP2 to deliver data let\nDP3 meet its objective", shape = note]; + comment_3 [label = "DP3 to deliver data let\nDP4 meet its objective", shape = note]; + comment_4 [label = "DP4 to deliver data\nto real time-sink", shape = note]; + + Comp_1 -> Comp_2 -> Comp_3 -> Comp_4 -> sink; + + comment_1 -> Comp_2 [style = dashed]; + comment_2 -> Comp_3 [style = dashed]; + comment_3 -> Comp_4 [style = dashed]; + comment_4 -> sink [style = dashed]; +} diff --git a/architectures/firmware/sof-zephyr/mpp_layer/mpp_scheduling.rst b/architectures/firmware/sof-zephyr/mpp_layer/mpp_scheduling.rst index c4ff5631..20b3df84 100644 --- a/architectures/firmware/sof-zephyr/mpp_layer/mpp_scheduling.rst +++ b/architectures/firmware/sof-zephyr/mpp_layer/mpp_scheduling.rst @@ -128,7 +128,7 @@ deadline for data delivery: EDF scheduling example -.. blockdiag:: images/mpp_scheduling/edf_scheduling.diag +.. graphviz:: images/mpp_scheduling/edf_scheduling.dot The capture pipelines operate in the same way. diff --git a/conf.py b/conf.py index c64f3493..1d2e9717 100755 --- a/conf.py +++ b/conf.py @@ -32,10 +32,8 @@ # ones. -# FIXME: blockdiag is orphaned and not compatible with Pillow anymore: -# https://github.com/thesofproject/sof-docs/issues/472 extensions = ['breathe', 'sphinx.ext.graphviz', 'sphinxcontrib.plantuml', - 'sphinx.ext.todo', 'sphinx.ext.extlinks', 'sphinxcontrib.blockdiag', + 'sphinx.ext.todo', 'sphinx.ext.extlinks', 'sphinxcontrib.jquery' ] diff --git a/scripts/requirements-lax.txt b/scripts/requirements-lax.txt index 42077b41..ae8a4076 100644 --- a/scripts/requirements-lax.txt +++ b/scripts/requirements-lax.txt @@ -13,7 +13,6 @@ breathe>=4.29.2 sphinx>=4.5.0 docutils>=0.17.1 sphinx_rtd_theme>=0.2.4 -sphinxcontrib-blockdiag>=3.0.0 sphinxcontrib-jquery # - Version 0.11 is the first version that supports @@ -56,8 +55,3 @@ sphinxcontrib.plantuml>=0.11 # - Downgrade if successfully tested. # - Test with plantum set to "none" in conf.py. We don't want small # typo fixes to depend on UML diagrams. - -# Workaround for warning "'ImageDraw' object has no attribute 'textsize'" -# with pillow 10.0.0, see -# https://github.com/thesofproject/sof-docs/issues/472 -pillow<10 diff --git a/scripts/requirements.txt b/scripts/requirements.txt index 17aff9e6..54b257e2 100644 --- a/scripts/requirements.txt +++ b/scripts/requirements.txt @@ -7,9 +7,3 @@ docutils sphinx_rtd_theme sphinxcontrib-plantuml sphinxcontrib-applehelp - - -# blockdiag is orphaned and not compatible with pillow>=10, -# see https://github.com/thesofproject/sof-docs/issues/472 -sphinxcontrib-blockdiag -pillow<10 From 12d2be406c0e04ea114037fdce215d36cb9fb684 Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Wed, 10 Jun 2026 20:26:51 +0100 Subject: [PATCH 2/6] docs: Pin the supported build with a lockfile The supported requirements.txt used unbounded ">=" specifiers (despite a comment claiming "==" pinning), so a new Sphinx or breathe release could break the build with no change to this repo, and two contributors could get different, unreproducible installs. Add scripts/constraints.txt, a lockfile pinning the full transitive dependency tree to exact, validated versions. The supported install now pairs requirements.txt (the readable top-level list) with this lockfile: pip install -r scripts/requirements.txt -c scripts/constraints.txt Wire it into the supported CI job and the docbuild instructions. The lock targets a modern Python (Sphinx 9 requires >= 3.11), so the CI job now uses actions/setup-python instead of the runner's system Python. Fix the stale requirements.txt header and drop the docbuild note about building pillow, which no longer applies now that blockdiag/pillow are gone. requirements-lax.txt stays loose for unpinned drive-by contributions. Co-Authored-By: Claude Opus 4.8 (1M context) Signed-off-by: Liam Girdwood --- .github/workflows/pull-request.yml | 11 ++++++-- contribute/process/docbuild.rst | 29 +++++++------------- scripts/constraints.txt | 43 ++++++++++++++++++++++++++++++ scripts/requirements.txt | 11 ++++++-- 4 files changed, 71 insertions(+), 23 deletions(-) create mode 100644 scripts/constraints.txt diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml index 11b29b37..262721c7 100644 --- a/.github/workflows/pull-request.yml +++ b/.github/workflows/pull-request.yml @@ -37,6 +37,13 @@ jobs: steps: - uses: actions/checkout@v3 + # The supported build is pinned by scripts/constraints.txt, which + # targets a modern Python (>= 3.11). Use setup-python rather than the + # runner's system Python so the lockfile installs as validated. + - uses: actions/setup-python@v5 + with: + python-version: '3.13' + # FIXME: remove this time consuming step once github stops # providing a broken package index, see # https://github.com/actions/virtual-environments/issues/1757#issuecomment-777700920 @@ -49,8 +56,8 @@ jobs: - name: PATH += .local/bin run: echo "$HOME/.local/bin" >> $GITHUB_PATH - - name: 'pip install -r scripts/requirements.txt' - run: pip install -r scripts/requirements.txt + - name: 'pip install -r scripts/requirements.txt -c scripts/constraints.txt' + run: pip install -r scripts/requirements.txt -c scripts/constraints.txt # No YAML anchors; this is copy/paste - name: configure SOF doc diff --git a/contribute/process/docbuild.rst b/contribute/process/docbuild.rst index 06570e03..98bb3859 100644 --- a/contribute/process/docbuild.rst +++ b/contribute/process/docbuild.rst @@ -151,30 +151,21 @@ tools: .. code-block:: bash cd ~/thesofproject/sof-docs - pip3 install --user -r scripts/requirements.txt + pip3 install --user -r scripts/requirements.txt -c scripts/constraints.txt -.. note:: The :git-sof-docs-mainline:`scripts/requirements.txt` file hardcodes - versions using ``==``, which may not be compatible with your other - projects. In that case you can either setup a Python ``virtualenv`` or - try the unsupported :git-sof-docs-mainline:`scripts/requirements-lax.txt` - (more details inside this file): +The :git-sof-docs-mainline:`scripts/constraints.txt` lockfile pins the full +dependency tree to exact, validated versions for a reproducible build. It +targets a modern Python (3.11 or newer); use a ``virtualenv`` if those pinned +versions conflict with your other projects. - .. code-block:: bash - - PIP_IGNORE_INSTALLED=0 pip3 install --user -r scripts/requirements-lax.txt - - The hardcoded package versions might need additional libraries installed - in order to compile them. For example, to resolve the following error: +.. note:: For a quick "best effort" install that is not pinned (for example a + drive-by typo fix), you can skip the lockfile and use the unsupported + :git-sof-docs-mainline:`scripts/requirements-lax.txt` instead (more details + inside this file): .. code-block:: bash - ERROR: Could not build wheels for pillow, which is required to install pyproject.toml-based projects - - you should install: - - .. code-block:: bash - - sudo apt install libjpeg-dev zlib1g-dev + PIP_IGNORE_INSTALLED=0 pip3 install --user -r scripts/requirements-lax.txt For Windows, install the needed tools manually: diff --git a/scripts/constraints.txt b/scripts/constraints.txt new file mode 100644 index 00000000..c06a6a2e --- /dev/null +++ b/scripts/constraints.txt @@ -0,0 +1,43 @@ +# scripts/constraints.txt — lockfile for the *supported* documentation build. +# +# This pins the full transitive dependency tree to exact, known-good +# versions so that the supported build is reproducible. Install with: +# +# pip install -r scripts/requirements.txt -c scripts/constraints.txt +# +# requirements.txt lists the top-level packages we depend on; this file +# locks every resolved version (direct and indirect). +# +# Validated on Python 3.14 (requires Python >= 3.11, the Sphinx 9 floor). +# +# To regenerate after intentionally bumping a dependency: +# python3 -m venv /tmp/lock && . /tmp/lock/bin/activate +# pip install -r scripts/requirements.txt +# pip freeze > scripts/constraints.txt # then re-add this header + +alabaster==1.0.0 +babel==2.18.0 +breathe==4.36.0 +certifi==2026.5.20 +charset-normalizer==3.4.7 +docutils==0.22.4 +idna==3.18 +imagesize==2.0.0 +Jinja2==3.1.6 +MarkupSafe==3.0.3 +packaging==26.2 +Pygments==2.20.0 +requests==2.34.2 +roman-numerals==4.1.0 +snowballstemmer==3.1.1 +Sphinx==9.1.0 +sphinx_rtd_theme==3.1.0 +sphinxcontrib-applehelp==2.0.0 +sphinxcontrib-devhelp==2.0.0 +sphinxcontrib-htmlhelp==2.1.0 +sphinxcontrib-jquery==4.1 +sphinxcontrib-jsmath==1.0.1 +sphinxcontrib-plantuml==0.31 +sphinxcontrib-qthelp==2.0.0 +sphinxcontrib-serializinghtml==2.0.0 +urllib3==2.7.0 diff --git a/scripts/requirements.txt b/scripts/requirements.txt index 54b257e2..48d602f8 100644 --- a/scripts/requirements.txt +++ b/scripts/requirements.txt @@ -1,5 +1,12 @@ -# This file hardcodes validated versions with '==', -# see requirements-lax.txt for an alternative. +# Top-level dependencies for the *supported* documentation build. +# +# For a reproducible install, pair this with the lockfile that pins the +# full transitive tree to exact, validated versions: +# +# pip install -r scripts/requirements.txt -c scripts/constraints.txt +# +# For an unpinned "best effort" install (e.g. a drive-by typo fix), see +# requirements-lax.txt instead. sphinx>=7 breathe From 5ac1cf9963fec2da20ad5358620abee7cb992992 Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Thu, 11 Jun 2026 09:01:48 +0100 Subject: [PATCH 3/6] ci: Modernize runners and add a Python matrix The CI ran on the pinned ubuntu-22.04 image and, for the lax job, installed the doc toolchain from distro packages (python3-sphinx, ...). That combination only ever exercised an old, distro-provided Python, so a dependency dropping support for current Python went unnoticed until a contributor hit it locally. Modernize the workflow: - Run every job on ubuntu-latest. - Build the supported (pinned) docs across a Python matrix (3.11, 3.13) with fail-fast disabled, so a pinned dependency that stops working on a given interpreter fails CI here instead of months later. Installs use setup-python + the requirements.txt/constraints.txt lockfile. - Publish the deploy artifact from a single canonical Python version (publish_python) so the matrix does not upload "html" twice. - Switch the lax job to setup-python + pip install of the loose requirements-lax.txt, dropping the fragile distro-package path. Also drop the now-obsolete "-j auto" workaround for Sphinx < 1.7. - Bump checkout and download-artifact to v4. Co-Authored-By: Claude Opus 4.8 (1M context) Signed-off-by: Liam Girdwood --- .github/workflows/pull-request.yml | 86 ++++++++++++++---------------- 1 file changed, 39 insertions(+), 47 deletions(-) diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml index 262721c7..d7a77a0a 100644 --- a/.github/workflows/pull-request.yml +++ b/.github/workflows/pull-request.yml @@ -26,40 +26,42 @@ on: # As of January 2021, no YAML anchors :-( env: ubuntu_base_deps: doxygen make default-jre graphviz cmake ninja-build + # The single Python version used to produce the published HTML, picked + # out of the matrix below to avoid duplicate deploy artifacts. + publish_python: '3.13' jobs: supported-reqs: - name: 'Supported scripts/requirements.txt' - runs-on: ubuntu-22.04 + name: 'Supported build (Python ${{ matrix.python-version }})' + runs-on: ubuntu-latest + + # Build against the lockfile on more than one Python so that a pinned + # dependency dropping support for a given interpreter is caught here + # rather than by a contributor months later. + strategy: + fail-fast: false + matrix: + python-version: ['3.11', '3.13'] steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - # The supported build is pinned by scripts/constraints.txt, which - # targets a modern Python (>= 3.11). Use setup-python rather than the - # runner's system Python so the lockfile installs as validated. - uses: actions/setup-python@v5 with: - python-version: '3.13' - - # FIXME: remove this time consuming step once github stops - # providing a broken package index, see - # https://github.com/actions/virtual-environments/issues/1757#issuecomment-777700920 - - name: apt-get update github broken package index - run: sudo apt-get update + python-version: ${{ matrix.python-version }} - - name: apt-get install - run: sudo apt-get -y install $ubuntu_base_deps - - - name: PATH += .local/bin - run: echo "$HOME/.local/bin" >> $GITHUB_PATH + - name: apt-get install base dependencies + run: | + sudo apt-get update + sudo apt-get -y install $ubuntu_base_deps - - name: 'pip install -r scripts/requirements.txt -c scripts/constraints.txt' + # Reproducible install: requirements.txt is the top-level list, + # constraints.txt pins the full transitive tree to validated versions. + - name: 'pip install -r requirements.txt -c constraints.txt' run: pip install -r scripts/requirements.txt -c scripts/constraints.txt - # No YAML anchors; this is copy/paste - name: configure SOF doc run: | git clone https://github.com/thesofproject/sof @@ -72,15 +74,17 @@ jobs: make html VERBOSE=1 SOF_DOC_BUILD=_build_doxy du -shc _build*/* + # Publish only from the canonical Python version so the matrix does + # not upload the "html" artifact twice. - name: prepare file for deploy - if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/publish' }} + if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/publish' && matrix.python-version == env.publish_python }} run: ./.github/actions/create-publish-folder.sh # store the build result to artifact, used for later deploy or # download for debug # https://docs.github.com/en/actions/guides/storing-workflow-data-as-artifacts - name: upload HTML for deploy - if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/publish' }} + if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/publish' && matrix.python-version == env.publish_python }} uses: actions/upload-artifact@v4 with: name: html @@ -88,13 +92,13 @@ jobs: deploy: needs: supported-reqs - runs-on: ubuntu-22.04 + runs-on: ubuntu-latest if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/publish' }} steps: # download the build result from the same workflow # https://docs.github.com/en/actions/guides/storing-workflow-data-as-artifacts - name: download HTML - uses: actions/download-artifact@v4.1.7 + uses: actions/download-artifact@v4 with: name: html path: html @@ -108,44 +112,32 @@ jobs: external_repository: thesofproject/thesofproject.github.io lax: - name: "PIP_IGNORE_INSTALLED=0 requirements-lax.txt" - runs-on: ubuntu-22.04 + name: "Lax requirements (unpinned)" + runs-on: ubuntu-latest # Makefile downgrades the Sphinx warnings, they are not errors any more env: {LAX: 1} steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - # FIXME: remove this time consuming step once github stops - # providing a broken package index, see - # https://github.com/actions/virtual-environments/issues/1757#issuecomment-777700920 - - name: apt-get update github broken package index - run: sudo apt-get update + - uses: actions/setup-python@v5 + with: + python-version: '3.13' - name: apt-get install base dependencies - run: sudo apt-get -y install $ubuntu_base_deps - - - name: apt-get instead of pip - run: sudo apt-get -y install - python3-pip python3-setuptools python3-wheel - python3-sphinx python3-breathe python3-docutils - python3-sphinx-rtd-theme python3-sphinxcontrib.plantuml - - - name: PATH += .local/bin - run: echo "$HOME/.local/bin" >> $GITHUB_PATH + run: | + sudo apt-get update + sudo apt-get -y install $ubuntu_base_deps - # should be a no-op + # Unpinned "best effort" install of the loose requirements, the path + # a drive-by contributor would take. No lockfile on purpose. - name: 'pip install -r scripts/requirements-lax.txt' run: pip install -r scripts/requirements-lax.txt - name: config tweaks run: | - # sphinx-build < 1.7 doesn't support "auto" and we're not sure - # all default modules are "thread-safe" - sed -i -e '/SPHINXBUILD/ s/-j *auto/-j 1/' Makefile # We don't want plantUML to raise the contribution bar sed -i -e 's/^\(plantuml_output_format *=\).*/\1 "none"/' conf.py - # No YAML anchors; this is copy/paste - name: configure SOF doc run: | git clone https://github.com/thesofproject/sof From b1a982e46294541a47020cdb55843391f55b987c Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Thu, 11 Jun 2026 10:25:28 +0100 Subject: [PATCH 4/6] docker: Fix and modernize the documentation build image The Dockerfile could not build: it ran "apt-get install python3.6" on ubuntu-22.04, where that package does not exist. Even past that line it was broken for the current toolchain -- ubuntu-22.04 ships Python 3.10, which cannot satisfy the supported requirements (Sphinx 9 needs >= 3.11), it ignored the constraints.txt lockfile, and it built Doxygen in source (-B sof/doc) while the sof-docs Makefile looks for the XML under ../sof/build_doxygen, so make html never found the API docs. Rebuild the image on ubuntu:24.04 (Python 3.12): - Install the toolchain into a venv (sidesteps PEP 668) from requirements.txt + constraints.txt, dropping the redundant distro python3-sphinx install. - Build Doxygen out of source into sof/build_doxygen, matching the Makefile's SOF_DOC_BUILD default, so no override is needed in the image. - Update docker-build.sh to copy that directory back to the host. Also replace the stale "(bad) default" TODO in the CI workflow with an accurate note: the Makefile default matches the documented sibling layout, and CI overrides it only because it checks sof out inside the sof-docs workspace. Co-Authored-By: Claude Opus 4.8 (1M context) Signed-off-by: Liam Girdwood --- .github/workflows/pull-request.yml | 5 +-- scripts/docker_build/Dockerfile | 53 ++++++++++++++++------------ scripts/docker_build/docker-build.sh | 4 +-- 3 files changed, 35 insertions(+), 27 deletions(-) diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml index d7a77a0a..3919a297 100644 --- a/.github/workflows/pull-request.yml +++ b/.github/workflows/pull-request.yml @@ -67,8 +67,9 @@ jobs: git clone https://github.com/thesofproject/sof cmake -GNinja -S sof/doc -B _build_doxy - # TODO: change the (bad) default value for SOF_DOC_BUILD in - # sof-docs/Makefile and remove this command line override + # SOF_DOC_BUILD overrides the Makefile default (../sof/build_doxygen, + # the documented sibling layout) because CI checks sof out *inside* + # the sof-docs workspace rather than alongside it. - name: build run: | make html VERBOSE=1 SOF_DOC_BUILD=_build_doxy diff --git a/scripts/docker_build/Dockerfile b/scripts/docker_build/Dockerfile index 070f7209..dd07a31a 100644 --- a/scripts/docker_build/Dockerfile +++ b/scripts/docker_build/Dockerfile @@ -5,14 +5,14 @@ # # Usage: # create parent directory for sof and sof-docs repository (e.g. thesofproject) -# clone sof repository to thesofproject\sof folder -# clone sof-docs repository to thesofproject\sof-docs folder -# build docker image from parent directory .\thesofproject: +# clone sof repository to thesofproject/sof folder +# clone sof-docs repository to thesofproject/sof-docs folder +# build docker image from parent directory ./thesofproject: # > docker build -t ubuntu-sofdocs -f ./sof-docs/scripts/docker_build/Dockerfile ./ # run the image container: # > docker run -d --name sofdocs_container ubuntu-sofdocs sleep infinity # copy build output from container to host: -# > docker cp sofdocs_container:/home/thesofproject/sof/doc ./sof/ +# > docker cp sofdocs_container:/home/thesofproject/sof/build_doxygen ./sof/ # > docker cp sofdocs_container:/home/thesofproject/sof-docs/_build ./sof-docs/ # stop the container: # docker stop sofdocs_container @@ -21,33 +21,40 @@ # but each next one will repeat only copy and build steps. # -FROM dokken/ubuntu-22.04 +FROM ubuntu:24.04 # Set image working directory WORKDIR /home/thesofproject -RUN apt-get update - -# Install sof-docs build tools -RUN apt-get install -y python3.6 -RUN apt-get install -y doxygen python3-pip python3-wheel make \ - default-jre graphviz cmake ninja-build - -# Copy sof-docs file with dependency tools list -COPY ./sof-docs/scripts/requirements.txt /home/thesofproject/sof-docs/scripts/requirements.txt - -# Install sof-docs requirements tools -RUN pip3 install --user -r /home/thesofproject/sof-docs/scripts/requirements.txt - -# Directly install sphinx to add 'sphinx-build' to the system -RUN apt-get install -y python3-sphinx +# Install sof-docs build tools. Ubuntu 24.04 ships Python 3.12, which +# satisfies the supported lockfile (Sphinx 9 requires Python >= 3.11). +RUN apt-get update && apt-get install -y --no-install-recommends \ + python3 python3-venv python3-pip \ + doxygen make default-jre graphviz cmake ninja-build \ + && rm -rf /var/lib/apt/lists/* + +# Install the Python tools into a venv (avoids Ubuntu's PEP 668 +# "externally managed environment" restriction) and put it first on PATH. +ENV VIRTUAL_ENV=/opt/venv +RUN python3 -m venv "$VIRTUAL_ENV" +ENV PATH="$VIRTUAL_ENV/bin:$PATH" + +# Install the pinned documentation toolchain from the lockfile. Copying +# only these two files first lets Docker cache the install layer across +# source changes. +COPY ./sof-docs/scripts/requirements.txt ./sof-docs/scripts/constraints.txt \ + /home/thesofproject/sof-docs/scripts/ +RUN pip install --no-cache-dir \ + -r sof-docs/scripts/requirements.txt -c sof-docs/scripts/constraints.txt # Copy sof source code from host to image COPY ./sof/ /home/thesofproject/sof/ -# Build API documentation from SOF source (Doxygen) -RUN cmake -S sof/doc -B sof/doc -GNinja -RUN ninja -C sof/doc -v doc +# Build API documentation from SOF source (Doxygen). Build out of source +# into sof/build_doxygen, which is where the sof-docs Makefile expects it +# (its SOF_DOC_BUILD default is ../sof/build_doxygen). +RUN cmake -GNinja -S sof/doc -B sof/build_doxygen +RUN ninja -C sof/build_doxygen -v doc # Copy sof-docs source code from host to image COPY ./sof-docs/ /home/thesofproject/sof-docs/ diff --git a/scripts/docker_build/docker-build.sh b/scripts/docker_build/docker-build.sh index e16e7507..dc8f4555 100644 --- a/scripts/docker_build/docker-build.sh +++ b/scripts/docker_build/docker-build.sh @@ -16,8 +16,8 @@ docker build -t ubuntu-sofdocs -f ./sof-docs/scripts/docker_build/Dockerfile ./ docker run -d --rm --name sofdocs_container ubuntu-sofdocs sleep infinity if [ $build_docs_only = "FALSE" ]; then - echo "Copy SOF Doxygen generated documentation from container to host ./sof/doc/" - docker cp sofdocs_container:/home/thesofproject/sof/doc ./sof/ + echo "Copy SOF Doxygen generated documentation from container to host ./sof/build_doxygen/" + docker cp sofdocs_container:/home/thesofproject/sof/build_doxygen ./sof/ fi echo "Copy SOF-DOCS generated documentation from container to host ./sof-docs/_build .." From 5aab674f067b2be970745cf8852e422d5334f8d7 Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Thu, 11 Jun 2026 10:35:11 +0100 Subject: [PATCH 5/6] ci: Build the API XML before the strict html build The supported job builds html with -W, so a doxygengroup referencing a group that no longer exists in sof turns into an error. Build the Doxygen XML explicitly in its own step (matching the documented two-step flow) rather than relying on the Makefile's apidocs target to trigger it as a side effect of "make html". This makes doc/source drift fail the PR with a clear, attributable step instead of silently dropping API sections. Co-Authored-By: Claude Opus 4.8 (1M context) Signed-off-by: Liam Girdwood --- .github/workflows/pull-request.yml | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml index 3919a297..77116542 100644 --- a/.github/workflows/pull-request.yml +++ b/.github/workflows/pull-request.yml @@ -62,10 +62,15 @@ jobs: - name: 'pip install -r requirements.txt -c constraints.txt' run: pip install -r scripts/requirements.txt -c scripts/constraints.txt - - name: configure SOF doc + - name: configure and build SOF API docs (Doxygen) run: | git clone https://github.com/thesofproject/sof cmake -GNinja -S sof/doc -B _build_doxy + # Build the API XML up front. The html build below is strict + # (-W), so any doc/source drift -- e.g. a doxygengroup that no + # longer exists in sof -- fails the PR here instead of silently + # dropping API sections. + ninja -C _build_doxy doc # SOF_DOC_BUILD overrides the Makefile default (../sof/build_doxygen, # the documented sibling layout) because CI checks sof out *inside* @@ -139,10 +144,11 @@ jobs: # We don't want plantUML to raise the contribution bar sed -i -e 's/^\(plantuml_output_format *=\).*/\1 "none"/' conf.py - - name: configure SOF doc + - name: configure and build SOF API docs (Doxygen) run: | git clone https://github.com/thesofproject/sof cmake -GNinja -S sof/doc -B _build_doxy + ninja -C _build_doxy doc - name: build run: | From 95d87bcc6adda626d9600afd26a6596aa30e8712 Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Thu, 11 Jun 2026 10:51:00 +0100 Subject: [PATCH 6/6] conf: Exclude in-tree virtualenvs from the Sphinx source scan A virtualenv created inside the sof-docs checkout (.venv, venv, env, ...) is otherwise walked by Sphinx, which then warns about the many .rst files shipped inside installed packages (docutils, etc.) -- around 50 spurious "document isn't included in any toctree" warnings that drown out real ones. Add the common venv directory names to exclude_patterns. Co-Authored-By: Claude Opus 4.8 (1M context) Signed-off-by: Liam Girdwood --- conf.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/conf.py b/conf.py index 1d2e9717..65ba72db 100755 --- a/conf.py +++ b/conf.py @@ -102,7 +102,10 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This patterns also effect to html_static_path and html_extra_path -exclude_patterns = ['_build','.tox' ] +# Note: a virtualenv created inside this source tree (.venv, venv, env, ...) +# would otherwise be scanned by Sphinx and flood the build with warnings +# about .rst files shipped in installed packages. +exclude_patterns = ['_build', '.tox', '.venv*', 'venv', 'env'] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx'