Skip to content

Commit 9559918

Browse files
Roger-luoRoger-luo
authored
Merge branch 'main' into dependabot/npm_and_yarn/docs/astro-6.1.10
2 parents 133b21a + 4726418 commit 9559918

21 files changed

Lines changed: 2025 additions & 64 deletions

File tree

‎.github/workflows/docs.yml‎

Lines changed: 175 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,76 +1,210 @@
11
name: Docs
22

3+
# Deploy the Astro docs site at `docs/` to GitHub Pages.
4+
#
5+
# Behaviour:
6+
# - Push to `main` → build with PPVM_BASE=/ and publish
7+
# to the gh-pages branch root.
8+
# - Pull request (opened / → build with PPVM_BASE=/pr-preview/pr-<N>
9+
# synchronize / reopened) and let rossjrw/pr-preview-action publish
10+
# the build to gh-pages under
11+
# `pr-preview/pr-<N>/`. Triggered only when
12+
# the diff actually touches inputs the
13+
# site depends on.
14+
# - Pull request closed → cleanup-preview job removes the
15+
# `pr-preview/pr-<N>/` subdirectory.
16+
#
17+
# The Rust API site under `/rust-api/` is published by `rust-docs.yml`
18+
# and survives our deploys via `keep_files: true`.
19+
320
on:
421
push:
522
branches: [main]
623
pull_request:
7-
types: [opened, synchronize, reopened, closed]
8-
24+
types: [opened, synchronize, reopened]
25+
paths:
26+
# Site sources, the Rust workspace (consumed by the API JSON
27+
# extractor), and the Python package (consumed by the notebook
28+
# build step + the Python API extractor).
29+
- "docs/**"
30+
- "crates/**"
31+
- "ppvm-python/**"
32+
- ".github/workflows/docs.yml"
33+
pull_request_target:
34+
types: [closed]
35+
36+
# No workflow-wide write privileges. Each job declares the narrowest
37+
# token scope it actually needs. The `build` job executes user-controlled
38+
# notebooks via `npm run extract:notebooks`, so its token must not be
39+
# able to push to `gh-pages` (or anything else). Deploys run on
40+
# separately-scoped jobs that don't see the notebook execution context.
941
permissions:
10-
contents: write
11-
pull-requests: write
42+
contents: read
1243

13-
env:
14-
RUSTFLAGS: "-C target-feature=+aes,+sse2"
44+
concurrency:
45+
# Serialise per-PR (and main); a fresh build cancels any in-flight one
46+
# for the same ref so PR comments don't pile up on rapid pushes.
47+
group: docs-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
48+
cancel-in-progress: true
1549

1650
jobs:
17-
deploy-preview:
18-
name: Deploy preview
19-
if: github.event_name == 'pull_request' && github.event.action != 'closed'
51+
build:
52+
# Build the static site once, upload it as an artifact, and let the
53+
# downstream jobs decide where (if anywhere) to publish it.
54+
if: github.event.action != 'closed'
55+
name: Build Astro site
2056
runs-on: ubuntu-latest
57+
# Notebook execution runs arbitrary repo-controlled Python here;
58+
# the token in this job stays read-only so a malicious PR can't
59+
# exfiltrate it into a gh-pages write.
60+
permissions:
61+
contents: read
62+
outputs:
63+
base: ${{ steps.compute-base.outputs.base }}
2164
steps:
2265
- uses: actions/checkout@v4
2366

24-
- uses: dtolnay/rust-toolchain@stable
67+
# Build inputs: nightly Rust for the rustdoc-JSON extractor,
68+
# uv to run griffe for the Python extractor, Node 20 for Astro.
69+
- uses: dtolnay/rust-toolchain@nightly
2570

2671
- uses: Swatinem/rust-cache@v2
2772

2873
- uses: astral-sh/setup-uv@v5
2974

30-
- name: Build docs
31-
run: uv run --project ppvm-python --group doc mkdocs build --config-file ppvm-python/mkdocs.yml
32-
33-
- name: Deploy PR preview
34-
uses: rossjrw/pr-preview-action@v1
75+
- uses: actions/setup-node@v4
3576
with:
36-
source-dir: ppvm-python/site/
37-
38-
cleanup-preview:
39-
name: Clean up preview
40-
if: github.event_name == 'pull_request' && github.event.action == 'closed'
77+
node-version: "20"
78+
cache: "npm"
79+
cache-dependency-path: docs/package-lock.json
80+
81+
- name: Install Astro deps
82+
# `npm ci` is faster than `npm install` and asserts the
83+
# lockfile is in sync; it fails loudly if package.json and
84+
# package-lock.json have drifted.
85+
run: npm ci
86+
working-directory: docs
87+
88+
- name: Compute base path
89+
id: compute-base
90+
run: |
91+
if [[ "${{ github.event_name }}" == "pull_request" ]]; then
92+
echo "base=/pr-preview/pr-${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT"
93+
else
94+
echo "base=/" >> "$GITHUB_OUTPUT"
95+
fi
96+
97+
- name: Compute git ref for source links
98+
id: compute-ref
99+
# "Source" links on the Examples pages resolve against this ref.
100+
# PR previews use the PR head SHA so new files (that aren't on
101+
# main yet) still link correctly; main deploys use the merge
102+
# commit SHA so the link is stable forever.
103+
run: |
104+
if [[ "${{ github.event_name }}" == "pull_request" ]]; then
105+
echo "ref=${{ github.event.pull_request.head.sha }}" >> "$GITHUB_OUTPUT"
106+
else
107+
echo "ref=${{ github.sha }}" >> "$GITHUB_OUTPUT"
108+
fi
109+
110+
- name: Build site
111+
# `npm run build` aggregates the three extraction steps
112+
# (`extract:rust`, `extract:python`, `extract:notebooks`) plus
113+
# `astro build` into a single command. See `docs/README.md`
114+
# for the per-step breakdown and the per-component escape
115+
# hatches a developer would use locally.
116+
working-directory: docs
117+
env:
118+
PPVM_SITE: https://congenial-bassoon-l436wp3.pages.github.io
119+
PPVM_BASE: ${{ steps.compute-base.outputs.base }}
120+
PPVM_GIT_REF: ${{ steps.compute-ref.outputs.ref }}
121+
RUSTFLAGS: "-C target-feature=+aes,+sse2"
122+
run: npm run build
123+
124+
- name: Upload built site
125+
uses: actions/upload-artifact@v4
126+
with:
127+
name: docs-dist
128+
path: docs/dist/
129+
if-no-files-found: error
130+
retention-days: 7
131+
132+
deploy-main:
133+
name: Deploy to gh-pages
134+
needs: build
135+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
41136
runs-on: ubuntu-latest
137+
# Only this job writes to gh-pages; it doesn't run any
138+
# repo-controlled scripts (the artifact is already built).
139+
permissions:
140+
contents: write
141+
concurrency:
142+
group: deploy-gh-pages
143+
cancel-in-progress: false
42144
steps:
43145
- uses: actions/checkout@v4
44146

45-
- uses: rossjrw/pr-preview-action@v1
147+
- uses: actions/download-artifact@v4
46148
with:
47-
source-dir: ppvm-python/site/
149+
name: docs-dist
150+
path: docs/dist/
48151

49-
deploy-dev:
50-
name: Deploy dev docs
51-
if: github.ref == 'refs/heads/main'
152+
- name: Publish to gh-pages root
153+
uses: peaceiris/actions-gh-pages@v3
154+
with:
155+
github_token: ${{ secrets.GITHUB_TOKEN }}
156+
publish_dir: ./docs/dist
157+
# Preserve /rust-api/ (managed by rust-docs.yml) and
158+
# /pr-preview/* (managed by pr-preview-action below).
159+
keep_files: true
160+
commit_message: "docs: deploy ${{ github.sha }}"
161+
162+
deploy-preview:
163+
name: Deploy PR preview
164+
needs: build
165+
if: github.event_name == 'pull_request' && github.event.action != 'closed'
52166
runs-on: ubuntu-latest
167+
# Writes the pre-built artifact to gh-pages/pr-preview/pr-<N>/
168+
# and comments back on the PR.
169+
permissions:
170+
contents: write
171+
pull-requests: write
53172
concurrency:
54-
group: deploy-dev
173+
group: deploy-gh-pages
55174
cancel-in-progress: false
56175
steps:
57176
- uses: actions/checkout@v4
58-
with:
59-
fetch-depth: 0 # mike needs full history to push to gh-pages
60-
61-
- uses: dtolnay/rust-toolchain@stable
62177

63-
- uses: Swatinem/rust-cache@v2
64-
65-
- uses: astral-sh/setup-uv@v5
178+
- uses: actions/download-artifact@v4
179+
with:
180+
name: docs-dist
181+
path: docs/dist/
66182

67-
- name: Configure git
68-
run: |
69-
git config user.name "github-actions[bot]"
70-
git config user.email "github-actions[bot]@users.noreply.github.com"
183+
- name: Deploy PR preview to gh-pages/pr-preview/pr-<N>
184+
uses: rossjrw/pr-preview-action@v1
185+
with:
186+
source-dir: docs/dist/
187+
preview-branch: gh-pages
188+
umbrella-dir: pr-preview
71189

72-
- name: Fetch gh-pages branch
73-
run: git fetch origin gh-pages --depth=1 || true
190+
cleanup-preview:
191+
name: Clean up PR preview
192+
if: github.event_name == 'pull_request_target' && github.event.action == 'closed'
193+
runs-on: ubuntu-latest
194+
# Removes the gh-pages/pr-preview/pr-<N>/ subtree and edits the
195+
# PR's preview comment; nothing else.
196+
permissions:
197+
contents: write
198+
pull-requests: write
199+
concurrency:
200+
group: deploy-gh-pages
201+
cancel-in-progress: false
202+
steps:
203+
- uses: actions/checkout@v4
74204

75-
- name: Deploy dev docs with mike
76-
run: uv run --project ppvm-python --group doc mike deploy dev --push --config-file ppvm-python/mkdocs.yml
205+
- uses: rossjrw/pr-preview-action@v1
206+
with:
207+
source-dir: docs/dist/
208+
preview-branch: gh-pages
209+
umbrella-dir: pr-preview
210+
action: remove

‎.github/workflows/rust-docs.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,8 @@ jobs:
4040
permissions:
4141
contents: write
4242
concurrency:
43-
group: deploy-rust-docs
44-
cancel-in-progress: true
43+
group: deploy-gh-pages
44+
cancel-in-progress: false
4545
steps:
4646
- uses: actions/checkout@v4
4747

‎AGENTS.md‎

Lines changed: 21 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,17 @@
11
# AGENTS.md
22

33
> **Read the Developer Guide first.** The canonical contributor reference for
4-
> this repository — for both human and AI contributors — lives in the docs
5-
> site at `docs/src/pages/develop.astro` (rendered at `/develop/`). It covers
6-
> project layout, build/test commands, architecture, conventions, the Python
7-
> binding pipeline, and where to look for each subsystem.
4+
> this repository — for both human and AI contributors — is the Astro page
5+
> at [`docs/src/pages/develop.astro`](docs/src/pages/develop.astro) (rendered
6+
> at `/develop/` on the live site). It covers project layout, build/test
7+
> commands for the Rust workspace, the Python package, **and the docs site
8+
> itself** (`§ 2 Build & test`), architecture, conventions, the Python
9+
> binding pipeline, extension recipes, and the file-by-file "where to look
10+
> for X" table.
811
>
9-
> This file is a short pointer so agents can find that guide quickly. Do not
10-
> add content here that belongs in the Developer Guide — keep the guide as
11-
> the single source of truth.
12+
> This file is a short pointer so agents can find that guide quickly. Do
13+
> not add content here that belongs in the Developer Guide — keep the
14+
> guide as the single source of truth.
1215
1316
## Install the ppvm-usage skill
1417

@@ -29,13 +32,19 @@ internals.
2932

3033
If you are an AI agent picking up a task in this repository:
3134

32-
1. Open `docs/src/pages/develop.astro` and read the sections relevant to your
33-
task. The "For AI agents" callout at the top tells you which sections are
34-
load-bearing.
35+
1. Open [`docs/src/pages/develop.astro`](docs/src/pages/develop.astro) and
36+
read the sections relevant to your task. The "For AI agents" callout at
37+
the top tells you which sections are load-bearing.
3538
2. Use `uv` for anything Python; never `pip`.
3639
3. Use Conventional Commits: `<type>(<scope>): <description>`.
37-
4. Build & test with the commands documented in the guide
38-
(`cargo test --workspace`, `uv run --project ppvm-python --group dev pytest …`).
40+
4. Build & test the relevant target:
41+
- **Rust workspace**: `cargo test --workspace`
42+
- **Python package**: `uv run --project ppvm-python --group dev pytest …`
43+
- **Docs site**: `cd docs && npm run build` (chains `extract:rust`,
44+
`extract:python`, `extract:notebooks`, then `astro build`).
45+
Per-step commands and the `astro:dev` / `astro:build` escape
46+
hatches are documented under `§ 2 → "This docs site"` in the
47+
Developer Guide and in [`docs/README.md`](docs/README.md).
3948
5. Respect the `Config`-trait generics in `ppvm-runtime`; do not introduce
4049
runtime dispatch where a compile-time bound suffices.
4150
6. Pauli propagation runs **backwards** (Heisenberg picture). Reverse the

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
[![Documentation](https://img.shields.io/badge/Documentation-6437FF)](https://congenial-bassoon-l436wp3.pages.github.io/dev/)
1+
[![Documentation](https://img.shields.io/badge/Documentation-6437FF)](https://congenial-bassoon-l436wp3.pages.github.io/)
22

33
* Python build: [![CI - python](https://github.com/QuEraComputing/ppvm/actions/workflows/python-ci.yml/badge.svg)](https://github.com/QuEraComputing/ppvm/actions/workflows/python-ci.yml)
44
* Rust build: [![CI - rust](https://github.com/QuEraComputing/ppvm/actions/workflows/rust-ci.yml/badge.svg)](https://github.com/QuEraComputing/ppvm/actions/workflows/rust-ci.yml)

‎docs/.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,7 @@ dist/
33
.astro/
44
src/data/rust-api.json
55
src/data/python-api.json
6+
# Outputs from `docs/scripts/build-notebooks.py`. The Jupytext sources
7+
# under `docs/notebooks/` are tracked; the executed HTML fragments,
8+
# their metadata, and the index are regenerated on every build.
9+
src/generated/

0 commit comments

Comments
 (0)