Build example separately (#82)

Author: lsbardel

.github/copilot-instructions.md

@@ -14,6 +14,8 @@ applyTo: '/**'
 * Never edit `readme.md` directly — it is generated from `docs/index.md` via `make docs`
 * To install all dependencies (including all optional extras) run `make install-dev`
 * Do not modify code unless the developer explicitly asks for a code change.
+* Never run `git commit` (or `git push`) unless the developer explicitly asks for it.
+  Preparing changes in the working tree is the deliverable; committing is the developer's action.
 * Never change code that works unless you have been asked by the developer to do so,
   or you have a good reason to believe the code is wrong.
 * Concentrate on fixing the problem, not on making the code look nice unless you are

.github/workflows/build.yml

@@ -54,6 +54,12 @@ jobs:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: ./build/coverage.xml
 
+  examples:
+    if: github.ref != 'refs/heads/main'
+    uses: ./.github/workflows/examples.yml
+    with:
+      upload: false
+
   image:
     if: github.ref == 'refs/heads/main'
     uses: ./.github/workflows/docker-multiarch.yml

.github/workflows/docker-multiarch.yml

@@ -8,13 +8,24 @@ on:
         type: string
 
 jobs:
+  build-examples:
+    uses: ./.github/workflows/examples.yml
+    with:
+      upload: true
+
   build-amd64:
+    needs: build-examples
     runs-on: ubuntu-latest
     env:
       GITHUB_TOKEN: ${{ github.token }}
 
     steps:
       - uses: actions/checkout@v4
+      - name: download examples output
+        uses: actions/download-artifact@v4
+        with:
+          name: examples-output
+          path: docs
       - name: Login to GitHub Container Registry
         uses: docker/login-action@v3
         with:
@@ -31,13 +42,19 @@ jobs:
         run: rops docker push ${{ inputs.image-name }} --arch
 
   build-arm64:
+    needs: build-examples
     runs-on: ubuntu-24.04-arm
     env:
       GITHUB_TOKEN: ${{ github.token }}
       DOCKER_BUILDKIT: 0
 
     steps:
       - uses: actions/checkout@v4
+      - name: download examples output
+        uses: actions/download-artifact@v4
+        with:
+          name: examples-output
+          path: docs
       - name: Login to GitHub Container Registry
         uses: docker/login-action@v3
         with:

.github/workflows/examples.yml

@@ -0,0 +1,37 @@
+name: examples
+
+on:
+  workflow_call:
+    inputs:
+      upload:
+        description: Upload the generated outputs as an artifact
+        type: boolean
+        default: true
+
+jobs:
+  build-examples:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_TOKEN: ${{ github.token }}
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+      - name: Install uv
+        run: pip install -U pip uv
+      - name: Install dependencies
+        run: uv sync --frozen --no-install-project --group docs --extra data
+      - name: build examples
+        run: uv run ./dev/build-examples
+      - name: upload examples output
+        if: inputs.upload
+        uses: actions/upload-artifact@v4
+        with:
+          name: examples-output
+          path: |
+            docs/assets/examples/
+            docs/examples/output/
+          if-no-files-found: error

dev/quantflow.dockerfile

@@ -4,10 +4,8 @@ FROM ghcr.io/astral-sh/uv:python3.14-bookworm-slim AS builder
 
 WORKDIR /build
 
-# Install Chromium for kaleido (Plotly static image export used by docs examples)
 # Install Node.js for Observable Framework frontend build
 RUN apt-get update && apt-get install -y --no-install-recommends \
-    chromium \
     nodejs \
     npm \
     && rm -rf /var/lib/apt/lists/*
@@ -18,7 +16,9 @@ COPY pyproject.toml uv.lock readme.md ./
 # Install dependencies (no root package, with needed extras)
 RUN uv sync --frozen --no-install-project --group docs --extra data
 
-# Copy source, generate example outputs and images, then build docs
+# Copy source and build docs
+# Example outputs and images must be prebuilt in the build context
+# (run `uv run ./dev/build-examples` locally, or the build-examples CI job)
 COPY mkdocs.yml ./
 COPY dev/ ./dev/
 COPY docs/ ./docs/
@@ -27,7 +27,6 @@ COPY frontend/ ./frontend/
 COPY app/ ./app/
 RUN npm --prefix frontend install
 RUN npm --prefix frontend run build
-RUN uv run ./dev/build-examples
 RUN uv run mkdocs build
 
 # Stage 2: Runtime stage