Skip to content

The animation engine for agents: blazingly fast math and 3D videos with Manim's Python API, on a Rust GPU core.

Python

Deploy documentation and coverage with bounded cleanup

Sina Atalayf85c4889bacb
diff --git a/.github/deploy/cleanup.py b/.github/deploy/cleanup.py
new file mode 100644
index 00000000..bbe97801
--- /dev/null
+++ b/.github/deploy/cleanup.py
@@ -0,0 +1,39 @@
+"""Delete one PR preview; a preview that was never built is already absent."""
+
+import json
+import os
+from urllib.error import HTTPError
+from urllib.parse import quote
+from urllib.request import Request, urlopen
+
+
+def delete_preview(account_id: str, worker: str, preview: str, token: str) -> None:
+ """Delete the preview, tolerating only the API's not-found response."""
+ request = Request(
+ "https://api.cloudflare.com/client/v4/accounts/"
+ f"{quote(account_id, safe='')}/workers/workers/"
+ f"{quote(worker, safe='')}/previews/{quote(preview, safe='')}",
+ method="DELETE",
+ headers={"Authorization": f"Bearer {token}"},
+ )
+ try:
+ with urlopen(request, timeout=30) as response:
+ result = json.load(response)
+ except HTTPError as error:
+ error.close()
+ if error.code != 404:
+ raise
+ print(f"{worker}/{preview} is already absent")
+ return
+ if not isinstance(result, dict) or result.get("success") is not True:
+ raise RuntimeError(f"Cloudflare did not confirm deletion of {worker}/{preview}")
+ print(f"Deleted {worker}/{preview}")
+
+
+if __name__ == "__main__":
+ delete_preview(
+ os.environ["CLOUDFLARE_ACCOUNT_ID"],
+ os.environ["WORKER"],
+ f"pr-{int(os.environ['PR_NUMBER'])}",
+ os.environ["CLOUDFLARE_API_TOKEN"],
+ )
diff --git a/.github/deploy/coverage.jsonc b/.github/deploy/coverage.jsonc
index db42f20f..6c89ea12 100644
--- a/.github/deploy/coverage.jsonc
+++ b/.github/deploy/coverage.jsonc
@@ -5,12 +5,11 @@
"name": "manimgx-coverage",
"compatibility_date": "2026-09-25",
"assets": { "directory": "../../htmlcov" },
- // main's report
+ // Academa's internal/manimgx-hosting Terraform unit owns the domain and Worker identity.
"workers_dev": false,
- "routes": [{ "pattern": "coverage.manimgx.academa.ai", "custom_domain": true }],
// each commit's report is a deployment in the preview "main" or "pr-<number>", at
- // <preview>-manimgx-coverage.<account subdomain>.workers.dev; a Worker keeps its 100 most
- // recently used previews, and each preview its last 100 deployments
+ // <preview>-manimgx-coverage.<account subdomain>.workers.dev; Cloudflare retains their
+ // deployment history within the account plan's preview limits
"preview_urls": true,
"previews": {}
}
diff --git a/.github/deploy/docs.jsonc b/.github/deploy/docs.jsonc
index a8b6a2e6..ced4fd0f 100644
--- a/.github/deploy/docs.jsonc
+++ b/.github/deploy/docs.jsonc
@@ -11,11 +11,10 @@
// a path that matches nothing gets the nearest 404.html, with status 404
"not_found_handling": "404-page"
},
- // the site's domain (as `site_url` in docs/zensical.toml)
+ // Academa's internal/manimgx-hosting Terraform unit owns the domain and Worker identity.
"workers_dev": false,
- "routes": [{ "pattern": "manimgx.academa.ai", "custom_domain": true }],
// a pull request is previewed at pr-<number>-manimgx-docs.<account subdomain>.workers.dev
- // (set explicitly: it defaults to `workers_dev`)
+ // (set explicitly because `workers_dev` is disabled)
"preview_urls": true,
"previews": {},
"observability": { "enabled": true }
diff --git a/.github/workflows/deploy-docs.yaml b/.github/workflows/deploy-docs.yaml
index 1b4e1f0c..6d36ce18 100644
--- a/.github/workflows/deploy-docs.yaml
+++ b/.github/workflows/deploy-docs.yaml
@@ -1,7 +1,7 @@
# The docs site, on Cloudflare Workers (.github/deploy/docs.jsonc): built on every push and
# pull request, deployed from main to https://manimgx.academa.ai, and previewed per pull request.
-# The build runs the repository's code and gets no secrets; the jobs that get them never run
-# it, they upload what the build made.
+# The build gets no secrets. Publishing uses the base branch's deployment configuration,
+# checked out separately from the artifact, which contains only the built site.
name: Deploy docs
@@ -26,8 +26,10 @@ jobs:
build:
name: Build
if: github.event.action != 'closed'
- runs-on: ubuntu-24.04
- timeout-minutes: 45
+ runs-on: macos-26
+ # A cold build compiles the engine and renders the full gallery before hundreds of
+ # short API examples. Measured cold work exceeds 45 minutes; warm builds reuse films.
+ timeout-minutes: 90
permissions:
contents: read
steps:
@@ -39,31 +41,79 @@ jobs:
with:
tool: just
- # the GPU the examples' videos are drawn with, on the CPU: Mesa's lavapipe (the narrated
- # examples speak from docs/voice/, where what they say is kept)
- - name: Install a GPU driver
- run: |
- sudo apt-get update
- sudo apt-get install --yes --no-install-recommends libvulkan1 mesa-vulkan-drivers
-
- uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+ - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+
+ - name: Check the docs interactions
+ run: bun test tests/docs
+
- uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
with:
workspaces: rust
shared-key: engine
save-if: ${{ github.ref == 'refs/heads/main' }}
- - name: Build the site
- run: just build-docs
+ - name: Identify the rendered examples
+ id: films
+ run: |
+ export MANIMGX_DOCS_RENDER_PROFILE="$(rustc --version);macOS=$(sw_vers -productVersion);build=$(sw_vers -buildVersion)"
+ printf 'MANIMGX_DOCS_RENDER_PROFILE=%s\n' "$MANIMGX_DOCS_RENDER_PROFILE" >> "$GITHUB_ENV"
+ uv run --frozen --no-default-groups --group docs python -m docs.examples --cache-key \
+ | jq -r '"key=\(.key)\nprefix=\(.prefix)"' >> "$GITHUB_OUTPUT"
+
+ - name: Validate the reference declarations
+ run: uv run --frozen pytest -q tests/docs/test_reference.py
+
+ - name: Restore rendered examples
+ uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+ with:
+ path: |
+ docs/content/films/
+ docs/.cache/films/
+ key: ${{ steps.films.outputs.key }}-
+ restore-keys: ${{ steps.films.outputs.prefix }}
+
+ - name: Fingerprint restored films
+ id: restored
+ run: |
+ state="$(uv run --frozen --no-default-groups --group docs python -m docs.examples --cache-state)"
+ echo "state=$state" >> "$GITHUB_OUTPUT"
+
+ # The archive is only transport; each film's inputs and checksums decide reuse.
+ - name: Render the examples
+ run: just render-docs
+
+ - name: Fingerprint completed films
+ id: completed
+ if: always() && github.ref == 'refs/heads/main' && steps.restored.outcome == 'success'
+ run: |
+ state="$(uv run --frozen --no-default-groups --group docs python -m docs.examples --cache-state)"
+ echo "state=$state" >> "$GITHUB_OUTPUT"
+
+ # Keep completed films even if another fails or the run is cancelled. Snapshots are
+ # immutable: a fresh key lets retries extend partial sets and retain repairs. Avoid
+ # uploading an unchanged set. Main supplies the shared cache; PRs only read it.
+ - name: Save rendered examples
+ if: >-
+ always() && github.ref == 'refs/heads/main'
+ && steps.completed.outcome == 'success'
+ && hashFiles('docs/.cache/films/*.json') != ''
+ && steps.completed.outputs.state != steps.restored.outputs.state
+ uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+ with:
+ path: |
+ docs/content/films/
+ docs/.cache/films/
+ key: ${{ steps.films.outputs.key }}-${{ github.run_id }}-${{ github.run_attempt }}
+
+ - name: Build the pages
+ run: just build-docs-pages
- uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
with:
name: docs
- path: |
- docs/site/
- .github/deploy/docs.jsonc
- # the deployment config lives in .github/, a hidden directory
+ path: docs/site/
include-hidden-files: true
if-no-files-found: error
retention-days: 7
@@ -74,14 +124,23 @@ jobs:
if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
runs-on: ubuntu-24.04
timeout-minutes: 10
- permissions: {}
+ permissions:
+ contents: read
environment:
name: docs
url: https://manimgx.academa.ai
steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ with:
+ ref: ${{ github.event.pull_request.base.sha || github.sha }}
+ persist-credentials: false
+ sparse-checkout: .github/deploy
+ sparse-checkout-cone-mode: false
+
- uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
with:
name: docs
+ path: docs/site
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
@@ -91,7 +150,7 @@ jobs:
--message "${GITHUB_SHA}"
env:
CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
- CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+ CLOUDFLARE_ACCOUNT_ID: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
preview:
name: Preview
@@ -103,14 +162,23 @@ jobs:
&& github.actor != 'dependabot[bot]'
runs-on: ubuntu-24.04
timeout-minutes: 10
- permissions: {}
+ permissions:
+ contents: read
environment:
name: docs-preview
url: ${{ steps.preview.outputs.url }}
steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ with:
+ ref: ${{ github.event.pull_request.base.sha || github.sha }}
+ persist-credentials: false
+ sparse-checkout: .github/deploy
+ sparse-checkout-cone-mode: false
+
- uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
with:
name: docs
+ path: docs/site
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
@@ -123,40 +191,41 @@ jobs:
echo "url=${url}" >> "${GITHUB_OUTPUT}"
env:
CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
- CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+ CLOUDFLARE_ACCOUNT_ID: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
WRANGLER_OUTPUT_FILE_PATH: ${{ runner.temp }}/wrangler.ndjson
PR_NUMBER: ${{ github.event.pull_request.number }}
HEAD_SHA: ${{ github.event.pull_request.head.sha }}
delete-preview:
- name: Delete the preview
+ name: Delete the ${{ matrix.site }} preview
if: >-
github.event.action == 'closed'
&& github.event.pull_request.head.repo.full_name == github.repository
&& github.actor != 'dependabot[bot]'
runs-on: ubuntu-24.04
timeout-minutes: 5
+ strategy:
+ fail-fast: false
+ matrix:
+ site: [docs, coverage]
permissions:
contents: read
environment:
- name: docs-preview
+ name: ${{ matrix.site }}-preview
deployment: false
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
+ ref: ${{ github.event.pull_request.base.sha || github.sha }}
persist-credentials: false
- sparse-checkout: .github/deploy/docs.jsonc
+ sparse-checkout: .github/deploy
sparse-checkout-cone-mode: false
- - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
-
- name: Delete the preview
- # a pull request that was never previewed has none to delete
- continue-on-error: true
- run: >-
- bunx "wrangler@${WRANGLER_VERSION}" preview delete --config .github/deploy/docs.jsonc
- --name "pr-${PR_NUMBER}" --skip-confirmation
+ # Only an absent preview is ignored; authentication and API failures fail the job.
+ run: python3 .github/deploy/cleanup.py
env:
CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
- CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+ CLOUDFLARE_ACCOUNT_ID: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
+ WORKER: manimgx-${{ matrix.site }}
PR_NUMBER: ${{ github.event.pull_request.number }}
diff --git a/tests/test_deployment.py b/tests/test_deployment.py
new file mode 100644
index 00000000..b74b10a1
--- /dev/null
+++ b/tests/test_deployment.py
@@ -0,0 +1,136 @@
+"""Deployment credentials see trusted configuration and failures stay visible."""
+
+import io
+import json
+import runpy
+import urllib.request
+from http.client import HTTPMessage
+from pathlib import Path
+from typing import Never
+from urllib.error import HTTPError
+from urllib.request import Request
+
+import pytest
+import yaml
+
+ROOT = Path(__file__).parents[1]
+CLEANUP = ROOT / ".github/deploy/cleanup.py"
+
+
+def test_docs_snapshots_can_resume_failures_and_save_repairs() -> None:
+ steps = yaml.safe_load(
+ (ROOT / ".github/workflows/deploy-docs.yaml").read_text(encoding="utf-8")
+ )["jobs"]["build"]["steps"]
+ restore, save = [
+ step for step in steps if step.get("uses", "").startswith("actions/cache/")
+ ]
+ # An immutable exact hit must never prevent saving a repaired or extended set.
+ # Prefix lookup selects the latest attempt for the same inventory first.
+ assert restore["with"]["path"] == save["with"]["path"]
+ prefix = "${{ steps.films.outputs.key }}-"
+ assert restore["with"]["key"] == prefix
+ assert save["with"]["key"].startswith(prefix)
+ assert "github.run_id" in save["with"]["key"]
+ assert "github.run_attempt" in save["with"]["key"]
+ condition = save["if"]
+ assert "always()" in condition # failure and cancellation must reach the save step
+ assert "github.ref == 'refs/heads/main'" in condition
+ assert "cache-hit" not in condition
+ assert "steps.completed.outcome == 'success'" in condition
+ assert "hashFiles('docs/.cache/films/*.json') != ''" in condition
+ before = next(step for step in steps if step.get("id") == "restored")
+ after = next(step for step in steps if step.get("id") == "completed")
+ assert before["run"] == after["run"]
+ assert "--cache-state" in before["run"]
+ assert "always()" in after["if"]
+ assert "steps.restored.outcome == 'success'" in after["if"]
+ assert "steps.completed.outputs.state != steps.restored.outputs.state" in condition
+
+
[email protected]("status", [401, 403, 429, 500])
+def test_cleanup_does_not_hide_api_failures(
+ monkeypatch: pytest.MonkeyPatch, status: int
+) -> None:
+ def rejected(request: Request, timeout: int) -> Never:
+ raise HTTPError(request.full_url, status, "rejected", HTTPMessage(), None)
+
+ monkeypatch.setattr(urllib.request, "urlopen", rejected)
+ delete = runpy.run_path(str(CLEANUP))["delete_preview"]
+ with pytest.raises(HTTPError) as error:
+ delete("account", "manimgx-docs", "pr-42", "test-token")
+ assert error.value.code == status
+
+
+def test_cleanup_of_a_preview_that_never_existed_succeeds(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ def missing(request: Request, timeout: int) -> Never:
+ raise HTTPError(request.full_url, 404, "not found", HTTPMessage(), None)
+
+ monkeypatch.setattr(urllib.request, "urlopen", missing)
+ delete = runpy.run_path(str(CLEANUP))["delete_preview"]
+ delete("account", "manimgx-docs", "pr-42", "test-token")
+
+
[email protected]("success", [True, False])
+def test_cleanup_requires_confirmation_and_deletes_only_the_named_preview(
+ monkeypatch: pytest.MonkeyPatch, success: bool
+) -> None:
+ def respond(request: Request, timeout: int) -> io.BytesIO:
+ assert request.method == "DELETE"
+ assert request.full_url == (
+ "https://api.cloudflare.com/client/v4/accounts/account/"
+ "workers/workers/manimgx-docs/previews/pr-42"
+ )
+ assert request.get_header("Authorization") == "Bearer test-token"
+ assert timeout == 30
+ return io.BytesIO(json.dumps({"success": success}).encode())
+
+ monkeypatch.setattr(urllib.request, "urlopen", respond)
+ delete = runpy.run_path(str(CLEANUP))["delete_preview"]
+ if success:
+ delete("account", "manimgx-docs", "pr-42", "test-token")
+ else:
+ with pytest.raises(RuntimeError, match="did not confirm"):
+ delete("account", "manimgx-docs", "pr-42", "test-token")
+
+
+ ("workflow", "build", "publish", "assets"),
+ [
+ ("deploy-docs", "build", "deploy", "docs/site"),
+ ("deploy-docs", "build", "preview", "docs/site"),
+ ("test", "coverage", "publish-coverage", "htmlcov"),
+ ],
+)
+def test_build_artifacts_cannot_supply_the_deployment_configuration(
+ workflow: str, build: str, publish: str, assets: str
+) -> None:
+ jobs = yaml.safe_load(
+ (ROOT / f".github/workflows/{workflow}.yaml").read_text(encoding="utf-8")
+ )["jobs"]
+ upload = next(
+ step["with"]
+ for step in jobs[build]["steps"]
+ if step.get("uses", "").startswith("actions/upload-artifact@")
+ )
+ assert upload["path"].rstrip("/") == assets
+ steps = jobs[publish]["steps"]
+ checkout = next(
+ step["with"]
+ for step in steps
+ if step.get("uses", "").startswith("actions/checkout@")
+ )
+ assert checkout["ref"] == "${{ github.event.pull_request.base.sha || github.sha }}"
+ assert checkout["sparse-checkout"] == ".github/deploy"
+ assert checkout["persist-credentials"] is False
+ download = next(
+ step["with"]
+ for step in steps
+ if step.get("uses", "").startswith("actions/download-artifact@")
+ )
+ assert download["path"] == assets
+ # Even a build that puts its own .github/deploy tree in the artifact cannot
+ # replace the trusted configuration at the workspace root.
+ injected_config = ROOT / download["path"] / ".github/deploy/docs.jsonc"
+ assert not injected_config.is_relative_to(ROOT / ".github/deploy")