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.pynew file mode 100644index 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.jsoncindex 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.jsoncindex 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.yamlindex 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: Buildif: 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: 90permissions:contents: readsteps:@@ -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.2with:workspaces: rustshared-key: enginesave-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.1with:name: docs- path: |- docs/site/- .github/deploy/docs.jsonc- # the deployment config lives in .github/, a hidden directory+ path: docs/site/include-hidden-files: trueif-no-files-found: errorretention-days: 7@@ -74,14 +124,23 @@ jobs:if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'runs-on: ubuntu-24.04timeout-minutes: 10- permissions: {}+ permissions:+ contents: readenvironment:name: docsurl: https://manimgx.academa.aisteps:+ - 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.1with: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.04timeout-minutes: 10- permissions: {}+ permissions:+ contents: readenvironment:name: docs-previewurl: ${{ 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.1with: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.ndjsonPR_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 }} previewif: >-github.event.action == 'closed'&& github.event.pull_request.head.repo.full_name == github.repository&& github.actor != 'dependabot[bot]'runs-on: ubuntu-24.04timeout-minutes: 5+ strategy:+ fail-fast: false+ matrix:+ site: [docs, coverage]permissions:contents: readenvironment:- name: docs-preview+ name: ${{ matrix.site }}-previewdeployment: falsesteps:- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1with:+ ref: ${{ github.event.pull_request.base.sha || github.sha }}persist-credentials: false- sparse-checkout: .github/deploy/docs.jsonc+ sparse-checkout: .github/deploysparse-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.pyenv: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.pynew file mode 100644index 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")