ci: use docs flavor for document generation

.devcontainer/docs-test/devcontainer.json

@@ -0,0 +1,4 @@
+{
+  "image": "ghcr.io/philips-software/amp-devcontainer-docs:${localEnv:IMAGE_VERSION}",
+  "workspaceFolder": "/workspaces/amp-devcontainer/test/docs/workspace"
+}

.devcontainer/docs/Dockerfile

@@ -0,0 +1,34 @@
+# syntax=docker/dockerfile:1
+
+ARG BASE_IMAGE=ghcr.io/philips-software/amp-devcontainer-base:edge
+FROM ${BASE_IMAGE}
+
+ARG DEBIAN_FRONTEND=noninteractive
+
+HEALTHCHECK NONE
+
+SHELL ["/bin/bash", "-Eeuo", "pipefail", "-c"]
+
+# Set default environment options
+ENV PYTHONPYCACHEPREFIX=/cache/.python
+
+# Install the base system with all tool dependencies
+RUN --mount=type=bind,source=.devcontainer/docs/apt-requirements.json,target=/tmp/apt-requirements.json \
+    --mount=type=bind,source=.devcontainer/docs/requirements.txt,target=/tmp/requirements.txt \
+    --mount=type=cache,target=/cache,sharing=locked \
+    --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    --mount=type=cache,target=/var/log,sharing=locked <<EOF
+
+    # Install the base system with all tool dependencies
+    apt-get update && jq -r 'to_entries | .[] | .key + "=" + .value' /tmp/apt-requirements.json | \
+        xargs apt-get install -y --no-install-recommends
+
+    # Install some tools via pip to get more recent versions, clean up afterwards
+    python3 -m pip install --break-system-packages --require-hashes --no-cache-dir --no-compile -r /tmp/requirements.txt
+    find / -regex '^.*\(__pycache__\|\.py[co]\)$' -delete
+    rm -rf "$(pip cache dir)"
+
+    # Update python alternative to the correct version
+    update-alternatives --install /usr/bin/python python /usr/bin/python3 10
+EOF

.devcontainer/docs/apt-requirements.json

@@ -0,0 +1,5 @@
+{
+  "graphviz": "14.1.2-1ubuntu1",
+  "plantuml": "1:1.2020.2+ds-6build1",
+  "python3-pip": "25.1.1+dfsg-1ubuntu2"
+}

.devcontainer/docs/devcontainer-metadata.json

@@ -0,0 +1,16 @@
+{
+  "remoteEnv": {
+    "LOCAL_WORKSPACE_FOLDER": "${localWorkspaceFolder}"
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "jebbs.plantuml@2.18.1",
+        "mhutchie.git-graph@1.30.0",
+        "ms-vsliveshare.vsliveshare@1.1.122",
+        "sbdl.sbdl@1.8.18",
+        "usernamehw.errorlens@3.28.0"
+      ]
+    }
+  }
+}

.devcontainer/docs/devcontainer.json

@@ -0,0 +1,31 @@
+{
+  "initializeCommand": "docker build -f .devcontainer/base/Dockerfile -t amp-devcontainer-base:local .",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "context": "../..",
+    "args": {
+      "BASE_IMAGE": "amp-devcontainer-base:local"
+    }
+  },
+  "remoteEnv": {
+    "CONTAINER_FLAVOR": "docs"
+  },
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "files.insertFinalNewline": true,
+        "files.trimTrailingWhitespace": true
+      },
+      "extensions": [
+        "github.copilot@1.388.0",
+        "github.vscode-github-actions@0.32.1",
+        "github.vscode-pull-request-github@0.152.0",
+        "jetmartin.bats@0.1.10",
+        "kherring.bats-test-runner@0.1.3",
+        "mhutchie.git-graph@1.30.0",
+        "ms-azuretools.vscode-docker@2.0.0",
+        "usernamehw.errorlens@3.28.0"
+      ]
+    }
+  }
+}

.devcontainer/docs/requirements.in

@@ -0,0 +1 @@
+sbdl==1.22.7

.github/RELEASE_TEMPLATE.md

@@ -12,6 +12,7 @@
 |-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
 | amp-devcontainer-base         | ghcr.io/philips-software/amp-devcontainer-base:{{ amp-devcontainer-base-version }}@{{ amp-devcontainer-base-sha }}                         |
 | amp-devcontainer-cpp          | ghcr.io/philips-software/amp-devcontainer-cpp:{{ amp-devcontainer-cpp-version }}@{{ amp-devcontainer-cpp-sha }}                            |
+| amp-devcontainer-docs         | ghcr.io/philips-software/amp-devcontainer-docs:{{ amp-devcontainer-docs-version }}@{{ amp-devcontainer-docs-sha }}                         |
 | amp-devcontainer-embedded-cpp | ghcr.io/philips-software/amp-devcontainer-embedded-cpp:{{ amp-devcontainer-embedded-cpp-version }}@{{ amp-devcontainer-embedded-cpp-sha }} |
 | amp-devcontainer-rust         | ghcr.io/philips-software/amp-devcontainer-rust:{{ amp-devcontainer-rust-version }}@{{ amp-devcontainer-rust-sha }}                         |
 

.github/dependabot.yml

@@ -21,6 +21,7 @@ updates:
     directories:
       - .devcontainer/base
       - .devcontainer/cpp
+      - .devcontainer/docs
       - .devcontainer/rust
     schedule:
       interval: weekly

.github/workflows/build-push-test.yml

@@ -43,6 +43,8 @@ jobs:
           - flavor: cpp
             dockerfile: .devcontainer/cpp/Dockerfile
             build-embedded-flavor: "false"
+          - flavor: docs
+            dockerfile: .devcontainer/docs/Dockerfile
           - flavor: embedded-cpp
             dockerfile: .devcontainer/cpp/Dockerfile
             build-embedded-flavor: "true"

.github/workflows/image-cleanup.yml

@@ -25,4 +25,4 @@ jobs:
         with:
           delete-orphaned-images: true
           delete-untagged: true
-          packages: amp-devcontainer,amp-devcontainer-cpp,amp-devcontainer-embedded-cpp,amp-devcontainer-rust
+          packages: amp-devcontainer,amp-devcontainer-base,amp-devcontainer-cpp,amp-devcontainer-docs,amp-devcontainer-embedded-cpp,amp-devcontainer-rust

.github/workflows/pr-image-cleanup.yml

@@ -21,7 +21,7 @@ jobs:
       - uses: dataaxiom/ghcr-cleanup-action@d52806a0dc70b430571a37da1fde39733ffd640f # v1.2.2
         with:
           delete-tags: pr-${{ github.event.pull_request.number }}
-          packages: amp-devcontainer,amp-devcontainer-cpp,amp-devcontainer-embedded-cpp,amp-devcontainer-rust
+          packages: amp-devcontainer,amp-devcontainer-base,amp-devcontainer-cpp,amp-devcontainer-docs,amp-devcontainer-embedded-cpp,amp-devcontainer-rust
 
   cleanup-cache:
     name: 🧹 Cleanup Cache

.github/workflows/release-build.yml

@@ -61,7 +61,7 @@ jobs:
     name: Update Release Notes (🍨 ${{ matrix.flavor }})
     strategy:
       matrix:
-        flavor: [base, cpp, embedded-cpp, rust]
+        flavor: [base, cpp, docs, embedded-cpp, rust]
     runs-on: ubuntu-latest
     permissions:
       # Please note that this is an overly broad scope, but GitHub does not

.github/workflows/update-dependencies.yml

@@ -16,7 +16,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        flavor: ["base", "cpp", "rust"]
+        flavor: [base, cpp, docs, rust]
     # Using our own container is required since we need all package sources
     # set-up correctly.
     container: ghcr.io/philips-software/amp-devcontainer-${{ matrix.flavor }}:edge
@@ -57,7 +57,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        flavor: ["cpp", "embedded-cpp", "rust"]
+        flavor: ["cpp", "docs", "embedded-cpp", "rust"]
         file: ["devcontainer-metadata.json", "devcontainer.json"]
     permissions:
       contents: read # peter-evans/create-pull-request inherits app permissions; so we only need contents: read here

.github/workflows/vulnerability-scan.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        flavor: ["cpp", "embedded-cpp", "rust"]
+        flavor: ["cpp", "docs", "embedded-cpp", "rust"]
     permissions:
       security-events: write # is needed by github/codeql-action/upload-sarif to upload sarif files
     steps:

.github/workflows/wc-document-generation.yml

@@ -15,6 +15,7 @@
   generate-documents:
     name: Generate Documents
     runs-on: ubuntu-latest
+    container: ghcr.io/philips-software/amp-devcontainer-docs:pr-1335
     permissions:
       contents: read
     steps:
@@ -24,12 +25,6 @@
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
-      - name: Install dependencies
-        run: |
-          set -Eeuo pipefail
-
-          sudo apt-get update && sudo apt-get install --no-install-recommends -y plantuml
-          python -m pip install sbdl==1.22.7
       - name: Build & Validate SBDL model
         run: sbdl -m compile test/cpp/integration-tests.bats test/cpp/features/*.feature test/embedded-cpp/integration-tests.bats test/embedded-cpp/features/*.feature > amp-devcontainer.sbdl
       - name: Create document control context

README.md

@@ -31,7 +31,7 @@ This repository contains [devcontainers](https://docs.github.com/en/codespaces/s
 - **Batteries Included** 🔋: Pre-configured tools for local development and continuous integration.
 - **Developer Experience** 👩‍💻: Minimal set-up time and maximal shift-left.
 - **Multi-platform Support** ⚙️: Compatible with x64 and arm64 hardware on Windows, Linux, and macOS.
-- **Image Flavors** 🍨: Dedicated containers for C++, embedded C++, and Rust development.
+- **Image Flavors** 🍨: Dedicated containers for C++, embedded C++, Rust, and documentation generation.
 - **IDE Integration** 💻: Fully compatible with GitHub Codespaces and VS Code.
 - **Semantic Versioning** 🔢: Clear versioning strategy for container images.
 - **Secure** 🔒: Emphasis on supply-chain security and compatible with Dependabot.
@@ -54,6 +54,7 @@ The following devcontainers are published towards the [GitHub Container Registry
 
 - [amp-devcontainer-base](https://github.com/orgs/philips-software/packages/container/package/amp-devcontainer-base); shared base image used by the other flavors
 - [amp-devcontainer-cpp](https://github.com/orgs/philips-software/packages/container/package/amp-devcontainer-cpp); the C++ container
+- [amp-devcontainer-docs](https://github.com/orgs/philips-software/packages/container/package/amp-devcontainer-docs); the documentation generation container
 - [amp-devcontainer-embedded-cpp](https://github.com/orgs/philips-software/packages/container/package/amp-devcontainer-embedded-cpp); the embedded C++ container
 - [amp-devcontainer-rust](https://github.com/orgs/philips-software/packages/container/package/amp-devcontainer-rust); the Rust container
 
@@ -69,22 +70,27 @@ It consolidates common tooling (e.g. certificates and test tooling) so that the
 
 #### amp-devcontainer-cpp
 
-The amp-devcontainer-cpp built from this repository contains compilers and tools to facilitate modern C++ development.
+The amp-devcontainer-cpp image built from this repository contains compilers and tools to facilitate modern C++ development.
 The amp-devcontainer-cpp includes support for host- and cross-compilation using gcc and clang compilers.
 Next to the compilers there is support for package management (using [CPM.cmake](https://github.com/cpm-cmake/CPM.cmake) and [Conan](https://conan.io/)) code-coverage measurement, mutation testing (using [mull](https://github.com/mull-project/mull)), fuzzing (using [libfuzzer](https://www.llvm.org/docs/LibFuzzer.html)) and static analysis and formatting (clang-format, clang-tidy, clangd, include-what-you-use).
 
 The default build system is set up to use CMake, Ninja and CCache.
 
+#### amp-devcontainer-docs
+
+The amp-devcontainer-docs image built from this repository contains tooling to generate documentation from repository sources.
+It includes [sbdl](https://sbdl.dev/) to capture the essence of system composition and behaviour in a simple yet powerful domain-specific language, together with [PlantUML](https://plantuml.com/) and [Graphviz](https://graphviz.org/) for rendering diagrams.
+
 #### amp-devcontainer-embedded-cpp
 
-The amp-devcontainer-embedded-cpp built from this repository contains the same tooling as amp-devcontainer-cpp, extended with support for embedded C++ development.
+The amp-devcontainer-embedded-cpp image built from this repository contains the same tooling as amp-devcontainer-cpp, extended with support for embedded C++ development.
 On top of the host- and cross-compilation support it adds the arm-gcc (arm-none-eabi) toolchain for cross-compilation towards the ARM Cortex architecture, together with debugging support for micro-controllers (using [cortex-debug](https://github.com/Marus/cortex-debug) and gdb-multiarch).
 
 The default build system is set up to use CMake, Ninja and CCache.
 
 #### amp-devcontainer-rust
 
-The amp-devcontainer-rust built from this repository contains the Rust ecosystem and additional tools to facilitate, embedded, Rust development.
+The amp-devcontainer-rust image built from this repository contains the Rust ecosystem and additional tools to facilitate, embedded, Rust development.
 The amp-devcontainer-rust includes support for host- and cross-compilation.
 Next to the Rust ecosystem there is support for code-coverage measurement, mutation testing (using [cargo-mutants](https://mutants.rs/)), fuzzing (using [rust-fuzz](https://rust-fuzz.github.io/book/introduction.html)) and static analysis and formatting (clippy, rustfmt).
 

test/docs/integration-tests.bats

@@ -0,0 +1,85 @@
+#!/usr/bin/env bats
+
+bats_require_minimum_version 1.5.0
+
+setup() {
+  load '/usr/local/bats-support/load'
+  load '/usr/local/bats-assert/load'
+
+  pushd ${BATS_TEST_DIRNAME}/workspace
+}
+
+teardown() {
+  popd
+}
+
+## This section contains tests for version correctness of the installed tools.
+#  Comparing the versions of the installed tools with the expected versions as
+#  pinned in the flavor's apt- and pip-requirements.
+
+# bats test_tags=Version,Graphviz
+@test "graphviz version should be aligned with the expected version" {
+  EXPECTED_VERSION=$(get_expected_semver_for graphviz)
+  INSTALLED_VERSION=$(dot -V 2>&1 | to_semver)
+
+  assert_equal "$INSTALLED_VERSION" "$EXPECTED_VERSION"
+}
+
+# bats test_tags=Version,Pip
+@test "pip version should be aligned with the expected version" {
+  EXPECTED_VERSION=$(get_expected_semver_for python3-pip)
+  INSTALLED_VERSION=$(pip --version | to_semver)
+
+  assert_equal "$INSTALLED_VERSION" "$EXPECTED_VERSION"
+}
+
+# bats test_tags=Version,Sbdl
+@test "sbdl version should be aligned with the expected version" {
+  EXPECTED_VERSION=$(grep sbdl ${BATS_TEST_DIRNAME}/../../.devcontainer/docs/requirements.in | to_semver)
+  INSTALLED_VERSION=$(sbdl --version | to_semver)
+
+  assert_equal "$INSTALLED_VERSION" "$EXPECTED_VERSION"
+}
+
+## This section contains tests for the functional correctness of the installed tools.
+
+# bats test_tags=Functional,Plantuml
+@test "plantuml should render a diagram to a png image" {
+  run plantuml -o build -tpng diagram.puml
+
+  assert_success
+  assert [ -f build/diagram.png ]
+}
+
+# bats test_tags=Functional,Graphviz
+@test "graphviz should render a graph to an svg image" {
+  run dot -Tsvg graph.dot
+
+  assert_success
+  assert_output --partial "<svg"
+}
+
+# bats test_tags=Functional,Sbdl
+@test "sbdl should compile a requirements model" {
+  run sbdl -m compile sample.sbdl
+
+  assert_success
+  assert_output --partial "req-doc-0001 is requirement"
+}
+
+function to_semver() {
+  grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+' | head -n1
+}
+
+function get_expected_version_for() {
+  local TOOL=${1:?}
+
+  jq -r "to_entries[] | select(.key | startswith(\"${TOOL}\")) | .value | sub(\"-.*\"; \"\")" \
+    ${BATS_TEST_DIRNAME}/../../.devcontainer/docs/apt-requirements.json
+}
+
+function get_expected_semver_for() {
+  local TOOL=${1:?}
+
+  get_expected_version_for ${TOOL} | to_semver
+}

test/docs/workspace/diagram.puml

@@ -0,0 +1,4 @@
+@startuml
+Alice -> Bob: Authentication Request
+Bob --> Alice: Authentication Response
+@enduml

test/docs/workspace/graph.dot

@@ -0,0 +1,4 @@
+digraph {
+  a -> b;
+  b -> c;
+}

test/docs/workspace/sample.sbdl

@@ -0,0 +1,5 @@
+#!sbdl
+req-doc-0001 is requirement {
+  custom:title is "Sample requirement"
+  description is "A sample requirement used to validate the sbdl toolchain"
+}