From 3b804e1525aed1ed1cd15b561f102f02fd08b514 Mon Sep 17 00:00:00 2001
From: Luca <luca@quantmind.com>
Date: Thu, 11 Jun 2026 21:43:39 +0100
Subject: [PATCH] Build example separately

---
 .github/copilot-instructions.md        |  2 ++
 .github/workflows/build.yml            |  6 +++++
 .github/workflows/docker-multiarch.yml | 17 ++++++++++++
 .github/workflows/examples.yml         | 37 ++++++++++++++++++++++++++
 dev/quantflow.dockerfile               |  7 +++--
 5 files changed, 65 insertions(+), 4 deletions(-)
 create mode 100644 .github/workflows/examples.yml

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 39be6e0d..0fb0657e 100644
--- a/.github/copilot-instructions.md
+++ b/.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
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 62b752d9..8f8dc830 100644
--- a/.github/workflows/build.yml
+++ b/.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
diff --git a/.github/workflows/docker-multiarch.yml b/.github/workflows/docker-multiarch.yml
index 756d40c7..a3fd7506 100644
--- a/.github/workflows/docker-multiarch.yml
+++ b/.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,6 +42,7 @@ 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 }}
@@ -38,6 +50,11 @@ jobs:
 
     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:
diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml
new file mode 100644
index 00000000..af31d5c2
--- /dev/null
+++ b/.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
diff --git a/dev/quantflow.dockerfile b/dev/quantflow.dockerfile
index a6faec94..623f2c45 100644
--- a/dev/quantflow.dockerfile
+++ b/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