Skip to content

ci(docs): restore Documentation workflow (CPU runner) to fix stable docs - #142

Open
ChrisRackauckas wants to merge 3 commits into
mainfrom
restore-documentation-ci
Open

ChrisRackauckas wants to merge 3 commits into
mainfrom
restore-documentation-ci

Conversation

@ChrisRackauckas

@ChrisRackauckas ChrisRackauckas commented May 31, 2026 •

Copy link
Copy Markdown
Member

Problem

https://docs.sciml.ai/HighDimPDE/stable/ is frozen at v1.2.1 (June 2022). The deepbsde tutorial (and all current content) shows up under /dev/ but never reaches /stable/, even though it's present in the v2.3.0 source.

Root cause

  1. No docs workflow on main. Docs CI was deliberately removed from GitHub Actions in ci(docs): remove documentation workflow from GHA #99 (merged 2024-07-17), and Add Documentation CI workflow #130 ("Add Documentation CI workflow") was closed unmerged. So nothing has deployed docs from main.
  2. v2.x tag builds segfault. The legacy documentation.yml that survived on the release tags ran on a self-hosted GPU runner and segfaulted (exit 139) during docs/make.jl ExpandTemplates, crashing before deploydocs. So no v2.x version (v2.0.0–v2.3.0) was ever published to gh-pages — versions.js still has DOCUMENTER_NEWEST = "v1.2.1", and stable → v1.2.1.

Net: dev is a stale leftover from an old successful deploy; stable cannot advance until a tagged release completes a clean docs build.

Fix

Restore .github/workflows/Documentation.yml, but run on ubuntu-latest (CPU) instead of the self-hosted GPU box:

  • Every executed @example block uses use_cuda = false. The use_cuda = true snippets are static ```julia fences (not evaluated), and no executed block does using CUDA. So the build needs no GPU, and the CPU runner sidesteps the segfault.
  • Triggers on push to main (deploys dev), tag pushes (deploys the version + repoints stable), and pull_request (build-only validation). Added workflow_dispatch so a maintainer can manually deploy against an existing tag.
  • Credentials are already in place: the repo has a valid DOCUMENTER_KEY secret and matching read-write deploy key.

Validation

This PR's own pull_request run exercises the full docs/make.jl build on ubuntu-latest (Documenter skips deploydocs on PRs, so it's a safe build-only check). Confirm it goes green before merging.

After merge — to actually repoint stable

stable only moves on a tagged-release build. Two options:

  1. Preferred: cut a fresh release (master is already at 2.5.0 but untagged past v2.3.0) → TagBot tags it → the tag build deploys and repoints stable.
  2. Immediate backfill: manually run this workflow via workflow_dispatch against tag v2.3.0 to deploy v2.3.0 docs and repoint stable without waiting for a new release.

🤖 Generated with Claude Code

Risk assessment

  • Risk: medium
  • Blast radius: Documentation deployment only; no solver or package API changes. Both CPU and self-hosted workflows can publish the same documentation ref.
  • Evidence: All 22 reported checks pass, including the new CPU build and the existing GPU Documentation job. Reviewed both workflows, docs/make.jl, page selection, and executed versus static CUDA examples.
  • Independent review: codex-cli gpt-6.1-sol rated it medium, high confidence: CPU documentation builds pass, but two independent deployment jobs remain enabled.
  • Merge: needs human review — consolidate documentation deployment before merging.

🤖 Automated review section from an AI agent running as Chris Rackauckas's account — not written or reviewed by Chris.

Fix by Muse CLI Code muse-wonder-full-1.0 (head 6c04bfb)

  • Removed the gpu-docs job from .github/workflows/GPU.yml, which built and deployed docs/make.jl with DOCUMENTER_KEY. GPU.yml now runs only the gpu-tests job, so .github/workflows/Documentation.yml is the sole documentation publisher and source-changing pushes to main no longer schedule two deployments.
  • Trimmed the Documentation.yml comment to the present-tense CPU requirement (use_cuda = false, no GPU required); the historical GPU failure account stays in this PR description.

Validation (exact commands, tail of real output):

  • Workflow publisher probe (parses every workflow YAML, asserts gpu-tests remains, counts workflows running docs/make.jl with DOCUMENTER_KEY) — before the fix: docs publishers (2): ['.github/workflows/Documentation.yml', '.github/workflows/GPU.yml'] / FAIL: expected exactly one docs publisher (exit 1); after the fix: GPU.yml jobs: ['gpu-tests'] / docs publishers (1): ['.github/workflows/Documentation.yml'] / PASS: exactly one docs publisher (exit 0).
  • python3 YAML parse of all 11 workflow files: all ok; git diff --check: exit 0. actionlint is unavailable in this environment.
  • typos .github/workflows/Documentation.yml .github/workflows/GPU.yml: exit 0. No .jl files change, so Runic has no files to format in this diff.
  • GROUP=QA julia --project -e 'using Pkg; Pkg.test()' (Julia 1.13.2, JULIA_NUM_THREADS=4): QA | 19 1 20 — 19 passes with one Persistent tasks error from local CUDA_Runtime_jll precompilation. The identical run on a clean checkout of the default branch gives the same 19 pass / 1 error summary, so that error is pre-existing and unrelated to this workflow-only diff; QA passed in CI at the previous head.
  • Pushed as 6c04bfb; CI started (checks pending at the single post-push look, typos-check already passing). CI was not waited on.

Next counted review must come from a smart model in a fresh session, not this fix session (risk.md § Independent reviews).

🤖 Posted by an AI agent — harness: Muse CLI Code · model: muse-wonder-full-1.0
Conversation: local fixer job SciML__HighDimPDE.jl__142 (no session URL)

ChrisRackauckas and others added 2 commits May 31, 2026 10:40
Docs CI was removed from GHA in #99 (2024-07) and #130 to restore it was
closed unmerged, so `main` has had no documentation workflow. As a result
`stable` is frozen at v1.2.1 (2022): no v2.x release ever deployed docs.

The v2.x tag builds that did run used a self-hosted GPU runner and
segfaulted (exit 139) during `docs/make.jl` ExpandTemplates, crashing
before `deploydocs`. Every executed `@example` block uses
`use_cuda = false` (the `use_cuda = true` snippets are static, non-executed
fences), so the build needs no GPU. Running on `ubuntu-latest` avoids the
segfault and deploys correctly. DOCUMENTER_KEY + deploy key are already
configured on the repo.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@ChrisRackauckas

Copy link
Copy Markdown
Member Author

🤖 Automated comment from an AI agent running as @ChrisRackauckas — not written or reviewed by Chris.

Independent review (devin / fusion-gpt-6-1-sol-high-sidekick-swe-2-medium), reviewer session unknown, reviewed head f92fdfe

  • Verdict: CHANGES
  • Risk assessment: low (L3: repository-local documentation CI; no package code, dependencies, numerical assertions or public APIs change)
  • Round / slot: 1 / 1

This is a blind code-only review by a session other than the PR author's, copied below from the reviewer's report with only the grading metadata removed. The posting agent did not re-run the reviewer's commands. A MERGE verdict is advice; merging is left to the maintainers.

Risk

low (L3: repository-local documentation CI; no package code, dependencies, numerical assertions or public APIs change)

Blocking findings

  • [P2] Retire the duplicate GPU documentation publisher. .github/workflows/Documentation.yml:36-40 adds a second execution of docs/make.jl, but .github/workflows/GPU.yml:40-61 still builds and deploys the same documentation with the same credentials. The targeted workflow probe confirms that source-changing pushes to main schedule both publishers, with distinct concurrency groups: Documentation-refs/heads/main and GPU Tests-refs/heads/main. Consequently the CPU workflow does not replace the GPU documentation job, and there is no mutual exclusion between their deployments. Reading the resolved Documenter 1.20.0 implementation shows fetch/commit/push without a retry: overlapping deployments can fail with a non-fast-forward rejection; sequential deployments can publish the GPU/Julia-1.10 output after the intended CPU/latest-Julia output. Remove gpu-docs while retaining gpu-tests, or make the GPU job build-only and retain one publisher. Duplicate scheduling is confirmed by running; an actual deployment race was not executed. <ref_snippet file="(a local scratch path)" lines="36-40" /> <ref_snippet file="(a local scratch path)" lines="40-61" />

  • Verdict: CHANGES

  • Round: 1

  • Blocking priorities: P2

Non-blocking findings

  • .github/workflows/Documentation.yml:19-22: the comment narrates an earlier GPU failure and claims every v2.x deployment was blocked. The checkout cannot establish that historical claim. Keep the present-tense CPU requirement explanation and put historical failure evidence in the change description instead. The CPU-only example execution did hold up in the local probe. <ref_snippet file="(a local scratch path)" lines="19-22" />

What I ran

  • AI reviewer: Devin, model fusion-gpt-6-1-sol-high-sidekick-swe-2-medium. No harness session ID was available. Review was code-only and blind; no PR body, comments, other reviews or author rating were read.
  • Exported the requested TMPDIR; preserved the inherited layered JULIA_DEPOT_PATH. Verification used scratch/repo-copy, not the reviewed checkout. The original checkout remained clean at the specified head.
  • git diff origin/main...HEAD, git diff --check origin/main...HEAD, root instruction-file checks and newest-commit trailer inspection. One added 40-line workflow; no whitespace errors; root AGENTS.md/CLAUDE.md and author harness/model trailers absent.
  • julia --version: Julia 1.13.2. No committed Julia Manifest or interpreter lock exists. Used docs/Project.toml and retained the resolved scratch Manifest.
  • UV_OFFLINE=1 uv run --locked python --version: exit 0, Python 3.15.0, with warning that --locked has no effect outside a project. There is no uv.lock or Python project; this is not locked-project Python verification. Evidence: scratch/uv-run.txt.
  • JULIA_PKG_OFFLINE=true JULIA_PKG_PRECOMPILE_AUTO=0 julia --color=no --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()': exit 0; Documenter 1.20.0, local HighDimPDE 2.7.1. Evidence: scratch/pkg-instantiate.log.
  • Affected suite: unshare --user --map-root-user --net env -u DOCUMENTER_KEY -u GITHUB_TOKEN -u CI -u GITHUB_ACTIONS CUDA_VISIBLE_DEVICES= JULIA_PKG_OFFLINE=true JULIA_NUM_PRECOMPILE_TASKS=13 julia --color=no --project=docs docs/make.jl. Precompile concurrency was derived from available memory and CPUs. Unchanged doctests, example expansion and cross-reference checks completed without reported failures. Overall exit 1: isolated-network link checks failed with curl exit 6, followed by makedocs error [:linkcheck] before rendering. CUDA initialization also logged unavailable-runtime errors but did not stop example evaluation. Evidence: scratch/docs-build.log.
  • ruby scratch/workflow_probe.rb repo: exit 0. YAML parsed; source-changing main pushes and non-draft PRs select both docs jobs with disjoint concurrency groups; docs-only main pushes and tags select the new job alone. Evidence and exact probe: scratch/workflow-probe.log, scratch/workflow_probe.rb.
  • typos .github/workflows/Documentation.yml: exit 0. Evidence: scratch/typos-documentation-yml.log.

What I did not verify

  • Successful online link checking, HTML rendering, authenticated deployment, GitHub-hosted execution or the suspected deployment race. The docs run is partial evidence, not a passing full build. No assertions or link checks were disabled.
  • actionlint was unavailable. Ruby parsing and trigger probes do not replace GitHub Actions schema/expression validation.
  • Unchanged solver/GPU/QA suites were not run for this workflow-only diff. The historical GPU segfault claim was not independently reproduced.

🤖 Posted by an AI agent — harness: Claude Code 2.1.322 · model: claude-sonnet-5-5
Conversation: local session 3878b54e-28f2-4a01-a176-a8f5468d1997 (no session URL)

Documentation.yml is the single documentation build and deploy workflow; GPU.yml keeps only the GPU test job.

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Co-Authored-By: Muse <noreply@meta.com>
Agent-Harness: Muse CLI Code
Agent-Model: muse-wonder-full-1.0
Agent-Session: local fixer job SciML__HighDimPDE.jl__142 (no session URL)

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant