move doc building into container

.github/workflows/build-docs.yml

@@ -8,23 +8,53 @@ jobs:
     steps:
     - uses: actions/checkout@v4
 
-    - name: Setup Pages
-      id: pages
-      uses: actions/configure-pages@v5
+    - uses: docker/setup-buildx-action@v3
+      id: setup
 
-    - name: Set up Python 3.13
-      uses: actions/setup-python@v5
+    - name: Cache Build
+      uses: actions/cache@v4
+      id: cache
       with:
-        python-version: '3.13'
-
-    - name: Install Dev dependencies
-      run: >
-        python3 -m pip install --disable-pip-version-check -r requirements-pip.txt &&
-        pip3 install --disable-pip-version-check --group doc
-
-    - name: Build HTML
+        # if the list or anything in these folders expected to change, then cache needs to be cleared and rebuilt, because it is keyed only by pyproject.toml hash
+        path: .cache
+        key: build-doc-${{ hashFiles('pyproject.toml','Dockerfile.build-doc') }}
+        restore-keys: |
+          build-doc-
+
+    - name: Create folders on cache miss
       run: |
-        sphinx-build docs docs/_build/html
+        mkdir -p .cache/var/cache/apt
+        mkdir -p .cache/var/lib/apt
+        mkdir -p .cache/root/.cache/pip
+        mkdir -p .cache/root/.distrib/rust
+        mkdir -p .cache/root/.cargo/registry
+
+    - name: Inject docker cache
+      uses: reproducible-containers/buildkit-cache-dance@v3.1.2
+      with:
+        cache-map: |
+          {
+            ".cache/var/cache/apt": "/var/cache/apt",
+            ".cache/var/lib/apt": "/var/lib/apt",
+            ".cache/root/.cache/pip": "/root/.cache/pip",
+            ".cache/root/.cargo/registry": "/root/.cargo/registry",
+            ".cache/root/.distrib/rust": "/root/.distrib/rust"
+          }
+
+    - name: Build Doc
+      uses: docker/build-push-action@v6
+      with:
+        push: false
+        platforms: linux/arm64
+        # do not cache layers
+        file: Dockerfile.build-doc
+        outputs: type=local,dest=docs/_build/html
+        provenance: false
+        context: .
+
+    - name: Setup Pages
+      id: pages
+      uses: actions/configure-pages@v5
 
     - name: Upload artifact
       uses: actions/upload-pages-artifact@v3

Dockerfile.build-doc

@@ -0,0 +1,25 @@
+# build (local):
+#     docker buildx create --use --driver=docker-container --name container --bootstrap
+#     docker buildx build . --cache-to type=local,dest=.cache,mode=max --cache-from type=local,src=.cache --platform=linux/arm64 --builder=container --progress plain -o docs/_build/html -f Dockerfile.build-doc
+
+FROM python:3.13 AS builder
+WORKDIR /app
+COPY LICENSE.md .
+COPY README.md .
+COPY requirements-pip.txt .
+COPY pyproject.toml .
+COPY docs docs/
+RUN \
+    --mount=type=cache,target=/root/.cache/pip,sharing=shared \
+    python3 -m venv .venv && \
+    . .venv/bin/activate && \
+    python3 -m pip install --disable-pip-version-check -r requirements-pip.txt && \
+    pip3 install --disable-pip-version-check --group doc
+RUN \
+    . .venv/bin/activate && \
+    echo "Building docs..." && \
+    sphinx-build docs docs/_build/html
+
+FROM scratch
+WORKDIR /
+COPY --from=builder /app/docs/_build/html .