ci(docs): build & deploy Astro docs to gh-pages with PR previews by Roger-luo · Pull Request #78 · QuEraComputing/ppvm

Roger-luo · 2026-05-18T03:52:32Z

Summary

Replaces the legacy mkdocs + mike deploy in docs.yml with an Astro build that publishes the new site under docs/ to GitHub Pages, plus per-PR previews under pr-preview/pr-<N>/.

What changed

`.github/workflows/docs.yml`

Four jobs:

Job	When	What
`build`	every PR + every push to main	Single source of truth — installs Node 20, `npm ci` in `docs/`, runs `npx astro build` with the appropriate `PPVM_BASE` (`/` for main, `/pr-preview/pr-<N>` for PRs). Uploads `docs/dist/` as an artifact.
`deploy-main`	push to main	Downloads the artifact and publishes to gh-pages root via `peaceiris/actions-gh-pages@v3` with `keep_files: true` (preserves `/rust-api/` from `rust-docs.yml` and any active `/pr-preview/*`).
`deploy-preview`	PR opened / synchronize / reopened	Downloads the same artifact and lets `rossjrw/pr-preview-action@v1` push it to `gh-pages/pr-preview/pr-<N>/`.
`cleanup-preview`	PR closed	Same action with `action: remove` — drops the preview directory.

The build job runs once and feeds both deploy jobs, so PRs are guaranteed to deploy the exact bundle that was verified to build.

PR triggers are scoped to docs/** + the workflow file: Rust- or Python-only PRs don't fire a docs build. The /api/ page reads JSON committed under docs/src/data/; regenerating it needs the nightly Rust toolchain and stays a manual local step (docs/scripts/extract-rust.mjs).

`docs/astro.config.mjs`

Reads PPVM_SITE and PPVM_BASE from env, defaults to / so npx astro dev and unscoped local builds still work without env tweaks. CI sets PPVM_BASE per deploy target.

`README.md`

Badge URL updated from /dev/ (legacy mkdocs path) to the gh-pages root.

Test plan

PR opens this workflow on itself — deploy-preview runs and posts a preview URL comment on the PR.
Visit the preview URL — internal links resolve under /pr-preview/pr-N/… (verified locally with PPVM_BASE=/pr-preview/pr-99 npx astro build).
On merge, deploy-main writes to the gh-pages branch root; /rust-api/ (from rust-docs.yml) and any active PR preview directory are preserved by keep_files: true.
Closing this PR triggers cleanup-preview, removing pr-preview/pr-<N>/ from gh-pages.

What this PR does not do

It doesn't remove the legacy mkdocs config under ppvm-python/docs/ or the stale /dev/ content currently on gh-pages. Both can go in a follow-up sweep.
It doesn't touch rust-docs.yml; that workflow still owns /rust-api/ independently.

🤖 Generated with Claude Code

The docs.yml workflow now builds the new Astro site under `docs/`, publishes it to the root of the gh-pages branch on push to main, and deploys a per-PR preview to `pr-preview/pr-<N>/` on every pull request that touches `docs/` (or the workflow itself). Workflow shape - `build` — single source of truth for the static site. Installs Node 20, runs `npm ci` against `docs/package-lock.json`, invokes `npx astro build` with `PPVM_BASE` set to either `/` (main) or `/pr-preview/pr-<N>` (PR). Upload the bundle as an artifact so downstream jobs deploy the *same* bytes that were verified to build. Skipped on close events (only cleanup runs there). - `deploy-main` — push artifact to `gh-pages` root via peaceiris/actions-gh-pages with `keep_files: true`. The `keep_files` flag preserves `/rust-api/` (managed by `rust-docs.yml`) and any `/pr-preview/*` content (managed by the preview job below). - `deploy-preview` — rossjrw/pr-preview-action@v1 publishes the artifact to `gh-pages/pr-preview/pr-<N>/`. - `cleanup-preview` — same action with `action: remove` on PR close. Path-scoped triggers: PR events only fire when `docs/**` or this workflow file changed, so Rust- or Python-only PRs don't trigger a docs build. The API JSON consumed by `/api/` is committed under `docs/src/data/`; regenerating it requires the nightly Rust toolchain and is a manual local step (`docs/scripts/extract-rust.mjs`). Astro config - `astro.config.mjs` now reads `PPVM_SITE` and `PPVM_BASE` from env, defaulting to `/` so `npx astro dev` and unscoped local builds keep working unchanged. CI sets `PPVM_BASE` per deploy target. README badge now points at the gh-pages root rather than the legacy `/dev/` mkdocs path. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/src/data/{rust,python}-api.json are .gitignore'd and produced by docs/scripts/extract-{rust,python}.mjs. The previous version of this workflow assumed they were committed; CI failed with 'Could not resolve "../data/rust-api.json" from src/pages/api.astro'. This commit: - Installs nightly Rust (the rustdoc-JSON output format requires it) - Installs uv (the Python extractor invokes 'uv run --with griffe') - Runs both extractors before 'npx astro build'. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

This PR replaces the legacy MkDocs deployment workflow with an Astro-based docs build and GitHub Pages publishing flow, including PR preview deployments.

Changes:

Updates the docs workflow to build docs/ with Node/Astro and deploy to gh-pages.
Adds environment-driven Astro site/base configuration.
Updates the README documentation badge link to the new Pages root.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File	Description
`README.md`	Updates the documentation badge target URL.
`docs/astro.config.mjs`	Makes Astro `site` and `base` configurable via environment variables.
`.github/workflows/docs.yml`	Replaces MkDocs/mike deployment with Astro build, main deploy, PR preview deploy, and cleanup jobs.

Comments suppressed due to low confidence (2)

.github/workflows/docs.yml:125

Preview deployments also push to the same gh-pages branch as deploy-main, but they are not in the deploy-docs concurrency group. A PR preview update or cleanup that overlaps a main deploy can race on the branch, causing one push to fail or the main deploy to preserve a stale preview snapshot. Serialize all gh-pages writers with the same concurrency group if previews and root docs are meant to coexist reliably.


      - uses: actions/download-artifact@v4
        with:
          name: docs-dist
          path: docs/dist/

.github/workflows/docs.yml:143

Cleanup removes a directory from the same gh-pages branch used by the root docs deploy, but it is not serialized with deploy-main (or the Rust docs deploy). If a cleanup overlaps another gh-pages publish, one action may push from a stale checkout or fail with a non-fast-forward error, leaving previews or docs in the wrong state. Use a shared concurrency group for all gh-pages writers.

    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

    types: [opened, synchronize, reopened, closed]
+    paths:
+      # Site sources. Other paths (crates/, ppvm-python/) don't affect
+      # the build because the API JSON consumed by /api/ is committed
+      # under docs/src/data/ and regenerated manually.
+      - "docs/**"
+      - ".github/workflows/docs.yml"


+          PPVM_BASE: ${{ steps.compute-base.outputs.base }}
+        run: npx astro build
+


+//   · local dev:           PPVM_SITE=http://localhost:4321         PPVM_BASE=/
+//   · main → gh-pages:     PPVM_SITE=https://queracomputing.github.io  PPVM_BASE=/ppvm
+//   · PR preview deploy:   PPVM_SITE=https://queracomputing.github.io  PPVM_BASE=/ppvm/pr-preview/pr-<N>
+const site = process.env.PPVM_SITE ?? "https://queracomputing.github.io";


+        id: compute-base
+        run: |
+          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            echo "base=/pr-preview/pr-${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "base=/" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Generate API JSON
+        # The /api/ page reads docs/src/data/{rust,python}-api.json,


github-actions · 2026-05-18T03:58:37Z

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-05-18 04:09 UTC

Roger-luo · 2026-05-18T04:00:22Z

@copilot apply changes based on the comments in this thread

Agent-Logs-Url: https://github.com/QuEraComputing/ppvm/sessions/10e9393a-1558-4794-8568-221858564600 Co-authored-by: Roger-luo <8445510+Roger-luo@users.noreply.github.com>

Copilot · 2026-05-18T04:04:25Z

@copilot apply changes based on the comments in this thread

Implemented the requested thread fixes in commit 95950b7:

cleanup now runs on unfiltered PR close events (pull_request_target: closed) so previews are removed reliably,
all gh-pages writers (docs main deploy, preview deploy, preview cleanup, rust-docs deploy) now share deploy-gh-pages concurrency,
Astro PPVM_SITE/PPVM_BASE guidance and default site now match the current workflow settings.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

astral.sh
- Triggering command: /usr/bin/curl curl -LsSf REDACTED _64-REDACTED-linux-gnu/lib/libpanic_unwind-46ac3e7472fc5aa9.rlib _64-REDACTED-linux-gnu/lib/libobject-d2e48e453c437e35.rlib _64-REDACTED-linux-gnu/lib/libmemchr-cfc2ca754b2c6b2c.rlib _64-REDACTED-linux-gnu/lib/libaddr2line-653ce301891bfcc7.rlib _64-REDACTED-linux-gnu/lib/libgimli-f2083e61f51ba4f1.rlib _64-REDACTED-linux-gnu/lib/libcfg_if-73db4e0fa3be753a.rlib _64-REDACTED-linux-gnu/lib/librustc_demangle-f735d2adf1a9e94e.rlib _64-REDACTED-linux-gnu/lib/libstd_detect-aa3fdd30f4e8b4c5.rlib _64-REDACTED-linux-gnu/lib/libhashbrown-4cc90577a87aec63.rlib _64-�� _64-REDACTED-linux-gnu/lib/libminiz_oxide-e620cbd8c2e94796.rlib _64-REDACTED-linux-gnu/lib/libadler2-f4c975b081f3bf63.rlib b96e17/build_scr--diagnostic-width=120 /lib/rustlib/x86node /lib/rustlib/x86/usr/local/bin/npm /lib/rustlib/x86run /lib/rustlib/x86extract:python (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Copilot AI review requested due to automatic review settings May 18, 2026 03:52

Copilot started reviewing on behalf of Roger-luo May 18, 2026 03:53

View session

Copilot AI reviewed May 18, 2026

View reviewed changes

Copilot started work on behalf of Roger-luo May 18, 2026 04:00

View session

fix(ci): address docs workflow review feedback

95950b7

Agent-Logs-Url: https://github.com/QuEraComputing/ppvm/sessions/10e9393a-1558-4794-8568-221858564600 Co-authored-by: Roger-luo <8445510+Roger-luo@users.noreply.github.com>

Copilot finished work on behalf of Roger-luo May 18, 2026 04:05

Roger-luo merged commit 26ee533 into main May 18, 2026
8 checks passed

Roger-luo deleted the ci/docs-deploy-astro branch May 18, 2026 04:09

Navigation Menu

Repository navigation

ci(docs): build & deploy Astro docs to gh-pages with PR previews - #78

ci(docs): build & deploy Astro docs to gh-pages with PR previews#78
Roger-luo merged 3 commits into
mainfrom
ci/docs-deploy-astro

Roger-luo commented May 18, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

github-actions Bot commented May 18, 2026 •

edited

Loading

Uh oh!

Roger-luo commented May 18, 2026

Uh oh!

Copilot AI commented May 18, 2026 •

edited

Loading

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		PPVM_BASE: ${{ steps.compute-base.outputs.base }}
		run: npx astro build

Conversation

Roger-luo commented May 18, 2026

Summary

What changed

.github/workflows/docs.yml

docs/astro.config.mjs

README.md

Test plan

What this PR does not do

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

github-actions Bot commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Roger-luo commented May 18, 2026

Uh oh!

Copilot AI commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

`.github/workflows/docs.yml`

`docs/astro.config.mjs`

`README.md`

github-actions Bot commented May 18, 2026 •

edited

Loading

Copilot AI commented May 18, 2026 •

edited

Loading