From 2ccf2bb485201af14aabc5f81500670a60c93a1b Mon Sep 17 00:00:00 2001
From: Thomas Pinder <tompinder@live.co.uk>
Date: Wed, 30 Sep 2026 22:14:53 +0200
Subject: [PATCH] docs: stage the docs on Cloudflare at
 impulso-next.quantclimate.com

Serve the Sphinx build from a Cloudflare Worker with static assets, the
same way as the quantclimate.com landing page, so that Cloudflare Web
Analytics covers the docs with no code in the repo. GitHub Pages keeps
serving impulso.quantclimate.com until the staging hostname checks out.

html_handling "none" serves each file at the URL Sphinx gives it;
_redirects maps / and /dir/ to their index.html.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015fagcMeo1LmLG2Dg3NybmQ
---
 .github/workflows/main.yml | 37 +++++++++++++++++++++++++++++++++++++
 docs/_redirects            |  5 +++++
 docs/conf.py               |  2 ++
 docs/wrangler.jsonc        | 19 +++++++++++++++++++
 4 files changed, 63 insertions(+)
 create mode 100644 docs/_redirects
 create mode 100644 docs/wrangler.jsonc

diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 9bfccd35..10b110f9 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -324,3 +324,40 @@ jobs:
       - name: Deploy documentation
         id: deployment
         uses: actions/deploy-pages@v5
+
+  deploy-docs-cloudflare:
+    # Serves the same build from Cloudflare (docs/wrangler.jsonc). Runs next to
+    # the GitHub Pages deploy while the docs are staged on a second hostname.
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: [quality, tests-and-type-check, build-docs]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    concurrency:
+      group: cloudflare-docs
+      cancel-in-progress: false
+    steps:
+      - name: Check out
+        uses: actions/checkout@v7
+
+      - name: Download the docs build
+        uses: actions/download-artifact@v8
+        with:
+          name: github-pages
+
+      - name: Unpack the docs build
+        run: |
+          mkdir -p docs/_build/html
+          tar -xf artifact.tar -C docs/_build/html
+
+      - name: Set up Node
+        uses: actions/setup-node@v7
+        with:
+          node-version: 24
+
+      - name: Deploy to Cloudflare
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
+        run: npx --yes wrangler@4.145.0 deploy --config docs/wrangler.jsonc
diff --git a/docs/_redirects b/docs/_redirects
new file mode 100644
index 00000000..df8e0e45
--- /dev/null
+++ b/docs/_redirects
@@ -0,0 +1,5 @@
+# Cloudflare static-asset rules, copied to the site root by html_extra_path.
+# html_handling is "none" in docs/wrangler.jsonc, so a directory URL only
+# serves its index.html through these rules.
+/ /index.html 200
+/*/ /:splat/index.html 200
diff --git a/docs/conf.py b/docs/conf.py
index b43d7dc0..bc8f4a2e 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -153,6 +153,8 @@
 ogp_social_cards = {"enable": False}
 html_static_path = ["stylesheets"]
 html_css_files = ["extra.css"]
+# Cloudflare serves the site; _redirects maps directory URLs to index.html.
+html_extra_path = ["_redirects"]
 html_theme_options = {
     "accent_color": "crimson",  # names the token family; stylesheets/extra.css re-tones the crimson scale to ledger oxblood
     "color_mode": "auto",  # follow the reader's light/dark preference
diff --git a/docs/wrangler.jsonc b/docs/wrangler.jsonc
new file mode 100644
index 00000000..54efc131
--- /dev/null
+++ b/docs/wrangler.jsonc
@@ -0,0 +1,19 @@
+// Cloudflare Workers configuration for the docs: the Sphinx HTML build is
+// served as static assets, with no Worker code. The `deploy-docs-cloudflare`
+// job in .github/workflows/main.yml deploys it on every push to main.
+{
+  "name": "impulso-docs",
+  "compatibility_date": "2026-09-30",
+  // Serve the docs only on the custom domain, not on workers.dev.
+  "workers_dev": false,
+  "preview_urls": false,
+  // Cloudflare creates the DNS record and certificate for this hostname.
+  // Staging hostname: GitHub Pages still serves impulso.quantclimate.com.
+  "routes": [{ "pattern": "impulso-next.quantclimate.com", "custom_domain": true }],
+  "assets": {
+    "directory": "./_build/html",
+    // Serve every file at exactly the URL Sphinx gives it (/page.html stays
+    // /page.html). docs/_redirects maps / and /dir/ to their index.html.
+    "html_handling": "none"
+  }
+}