docs: variant-dependent documentation without Jinja, the same in Sphinx and ubCode

.devcontainer/Dockerfile

@@ -23,7 +23,7 @@ ENV NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt
 ENV REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
 ENV PIP_CERT=/etc/ssl/certs/ca-certificates.crt
 
-# Python toolchain (uv/CPython 3.11/Poetry) baked as the vscode user, so it lands
+# Python toolchain (uv/CPython 3.12/Poetry) baked as the vscode user, so it lands
 # in /home/vscode/.local (owned by the runtime user) and is on PATH the instant the
 # container starts. Same script bare WSL and CI run at runtime — one source of truth.
 COPY bootstrap_python.sh /tmp/bootstrap_python.sh

.github/workflows/ci.yml

@@ -41,6 +41,60 @@ jobs:
                   echo "Selected gate marker: $marker"
                   echo "marker=$marker" >> "$GITHUB_OUTPUT"
 
+    documentation:
+        name: Documentation
+        runs-on: ubuntu-24.04
+        timeout-minutes: 30
+        needs: determine-gate
+
+        # The documentation of every variant and kit, in both readers, in strict
+        # mode, with their needs compared (test/test_docs_gate.py). Each cell is
+        # CONFIGURED: codelinks takes a variant's #ifdef branches from its
+        # build's compile database, which only CMake writes. The reports shape
+        # also compiles each test-kit variant and runs its tests, because the
+        # test specifications, results and listings are what that run generates.
+        # The runner's gcc, g++, cmake and ninja are enough -- no poks, no scoop,
+        # no cross-compiler. It covers every variant, where the build jobs cover
+        # the variants they build.
+        steps:
+            - name: Checkout Code
+              uses: actions/checkout@v6
+              with:
+                  fetch-depth: 0
+
+            - name: Set up Python
+              uses: actions/setup-python@v6
+              with:
+                  python-version: "3.12"
+
+            - name: Install documentation dependencies
+              run: |
+                  pipx install poetry==2.4.1
+                  poetry config virtualenvs.in-project true
+                  poetry install --no-root
+
+            # cmake and gcc are part of the runner image; Ninja is the generator
+            # the builds use.
+            - name: Install Ninja
+              run: sudo apt-get install -y --no-install-recommends ninja-build
+
+            # `ubc` is the second reader. Without it the parity tests skip, and
+            # a guarantee that only holds on a developer machine is not a
+            # guarantee -- so the gate installs it and CI_REQUIRE_UBC turns a
+            # skip into a failure. No licence is needed for `check`; the inputs
+            # are passed anyway so that adding the secrets later just works.
+            - name: Install ubc
+              uses: useblocks/ubc-action@0.1
+              with:
+                  version: "0.35.0"
+                  license-key: ${{ secrets.UBCODE_LICENSE_KEY }}
+                  license-user: ${{ secrets.UBCODE_LICENSE_USER }}
+
+            - name: Documentation gate
+              env:
+                  CI_REQUIRE_UBC: "1"
+              run: poetry run pytest -m "docs and ${{ needs.determine-gate.outputs.marker }}"
+
     test-on-windows:
         name: Build and Test on Windows
         runs-on: windows-2025

.gitignore

@@ -1,6 +1,16 @@
 # Binary output dir, not recommended to push binary results to Git.
 /build
 
+# ubc's default output (`ubc build html` without -o writes _build/html), and
+# Sphinx's conventional `_build/<builder>`. SPLed's own commands write under
+# build/; this catches a bare run.
+/_build/
+
+# The document rules tools/variant_data.py generates whenever a variant is
+# selected (see ubproject.toml). Generated output, never committed; the
+# selection itself lives under /build.
+/ubproject.variants.toml
+
 # Output directory of test results
 /test/output
 

.vscode/settings.json

@@ -14,8 +14,15 @@
         "editor.defaultFormatter": "josetr.cmake-language-support-vscode"
     },
     "cmake.configureOnOpen": false,
+    // Generated output. tools/variant_data.py writes the variant data here and
+    // CMake writes everything else; an edit under build/ is lost on the next
+    // configure, and worse, it looks like it worked. Making the editor refuse
+    // the edit is the only guard rail that also applies to an assistant.
+    "files.readonlyInclude": {
+        "build/**": true,
+        "ubproject.variants.toml": true
+    },
     "cmake.buildDirectory": "${workspaceFolder}/build/${variant:variant}/${buildKit}/${buildType}",
-    "cmake.copyCompileCommands": "${workspaceFolder}/build/compile_commands.json",
     "cmake.configureSettings": {
         "BUILD_KIT": "${buildKit}",
         "CMAKE_MESSAGE_LOG_LEVEL": "STATUS",

.vscode/tasks.json

@@ -27,6 +27,58 @@
             },
             "problemMatcher": []
         },
+        {
+            "label": "Select documentation variant",
+            "detail": "Point the docs and ubCode at one variant -- no CMake, no compiler",
+            "type": "shell",
+            // Always the docs cell. Choosing `reports` here would open every
+            // report fence in the IDE, and each one globs into build/**, which
+            // ubCode excludes -- so every component would report an unmatched
+            // glob. CMake writes the docs cell as the pointer for the same
+            // reason. The target choice belongs to the build task below, which
+            // is where it changes what is produced rather than what is linted.
+            "command": "${command:python.interpreterPath} tools/variant_data.py --variant ${input:variant} --kit ${input:buildKit} --target docs --current",
+            "problemMatcher": [],
+            "presentation": {
+                "reveal": "silent",
+                "panel": "shared"
+            }
+        },
+        {
+            "label": "Generate all variant data",
+            "detail": "Write build/variants/<Variant>/<kit>/<target>.json for every variant",
+            "type": "shell",
+            "command": "${command:python.interpreterPath} tools/variant_data.py --all",
+            "problemMatcher": []
+        },
+        {
+            "label": "Build documentation for a variant",
+            "detail": "Sphinx docs for one variant, without configuring or building the software",
+            "type": "shell",
+            "command": "${command:python.interpreterPath} -m sphinx -b html -D needs_variant_data_file=build/variants/${input:variant}/${input:buildKit}/${input:docsTarget}.json . build/docs/${input:variant}",
+            "options": {
+                "env": {
+                    "VARIANT": "${input:variant}"
+                }
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Documentation gate (all variants)",
+            "detail": "What CI's compiler-free job runs: generate every variant and build its documents",
+            "type": "shell",
+            "command": "${command:python.interpreterPath} -m pytest -m docs",
+            "group": "test",
+            "problemMatcher": []
+        },
+        {
+            "label": "Check documentation with ubc (all variants)",
+            "detail": "Lint every variant with the reader that never runs conf.py",
+            "type": "shell",
+            "command": "${command:python.interpreterPath} -m pytest -m docs -k ubc",
+            "group": "test",
+            "problemMatcher": []
+        },
         {
             "label": "Open variant test report",
             "detail": "Open the variant's overall test report in your web browser",
@@ -43,7 +95,7 @@
         {
             "label": "Open variant coverage report",
             "detail": "Open the variant's overall coverage report in your web browser",
-            "command": "${workspaceFolder}/build/${input:variant}/test/Debug/reports/coverage/index.html",
+            "command": "${workspaceFolder}/build/${input:variant}/test/Debug/reports/html/build/${input:variant}/test/Debug/reports/coverage/index.html",
             "type": "shell",
             "presentation": {
                 "reveal": "always"
@@ -56,7 +108,7 @@
         {
             "label": "Open component test report",
             "detail": "Open the component's test report in your web browser",
-            "command": "${workspaceFolder}/build/${input:variant}/test/Debug/${input:component}/reports/html/index.html",
+            "command": "${workspaceFolder}/build/${input:variant}/test/Debug/${input:component}/reports/html/doc/component_report.html",
             "type": "shell",
             "presentation": {
                 "reveal": "always"
@@ -69,7 +121,7 @@
         {
             "label": "Open component coverage report",
             "detail": "Open the component's coverage report in your web browser",
-            "command": "${workspaceFolder}/build/${input:variant}/test/Debug/${input:component}/reports/coverage/index.html",
+            "command": "${workspaceFolder}/build/${input:variant}/test/Debug/reports/html/build/${input:variant}/test/Debug/${input:component}/reports/coverage/index.html",
             "type": "shell",
             "presentation": {
                 "reveal": "always"
@@ -111,6 +163,24 @@
                 "components/spled"
             ]
         },
+        {
+            "type": "pickString",
+            "id": "buildKit",
+            "description": "Which build kit? (the test kit adds a variant's test suites to its component list)",
+            "options": [
+                "test",
+                "prod"
+            ]
+        },
+        {
+            "type": "pickString",
+            "id": "docsTarget",
+            "description": "Which build shape? (reports additionally shows the generated test and coverage pages)",
+            "options": [
+                "docs",
+                "reports"
+            ]
+        },
         {
             "type": "pickString",
             "id": "buildType",