docs: stage the docs on Cloudflare at impulso-next.quantclimate.com

[thomaspinder]

Motivation

The docs are served by GitHub Pages, outside the Cloudflare zone that serves the rest of quantclimate.com. Because of that, Cloudflare Web Analytics cannot see the docs (see #367 and #372). The landing page is a Cloudflare Worker that serves static assets, and Cloudflare adds the analytics beacon to it at the edge with no code in the repo. This PR serves the docs the same way.

This is the staging step. The docs deploy to impulso-next.quantclimate.com, and GitHub Pages keeps serving impulso.quantclimate.com unchanged. A follow-up PR moves the real hostname once staging checks out.

Solution

• docs/wrangler.jsonc: a Worker named impulso-docs that serves the Sphinx build as static assets, on the custom domain impulso-next.quantclimate.com. No Worker code, no workers.dev URL.
• html_handling: "none" serves each file at exactly the URL Sphinx gives it, so /page.html stays /page.html. Cloudflare's default mode would redirect every .html URL to an extensionless one, away from the canonical links and the sitemap.
• docs/_redirects (copied to the site root by html_extra_path) serves / and /dir/ from their index.html.
• New job deploy-docs-cloudflare: on pushes to main, it takes the same build artifact that the GitHub Pages job deploys and runs wrangler deploy (Wrangler 4.145.0, Node 24). It reads the CLOUDFLARE_API_TOKEN org secret and the CLOUDFLARE_ACCOUNT_ID org variable. The build job does not change and has no access to the token.

Verification

Run locally with Wrangler 4.145.0 against the current production build (the github-pages artifact from main):

• wrangler deploy --dry-run --config docs/wrangler.jsonc: config is valid, 372 files read.
• wrangler dev with this exact config: /, /index.html, /tutorials/, /explanation/, /how-to/, /reference/, /_modules/, /genindex.html, /search.html?q=var, /objects.inv, /sitemap.xml, /render-mode.txt and /_static/basic.css all return 200. /nope.html returns 404. Both redirect rules parse.
• A throwaway Sphinx 9.0.4 build confirms that html_extra_path copies _redirects to the output root and that wrangler.jsonc does not leak into the site.
• ruff check, ruff format --check and actionlint pass.

After the merge: the job attaches impulso-next.quantclimate.com. Then check that the URLs above behave the same on that hostname and that page views appear in Cloudflare Web Analytics under that host.

Before merging

The CLOUDFLARE_API_TOKEN org secret must exist. Without it, the new job fails on main.

🤖 Generated with Claude Code

https://claude.ai/code/session_015fagcMeo1LmLG2Dg3NybmQ

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!