Skip to content

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

Open
ChrisRackauckas wants to merge 1 commit into
mainfrom
restore-documentation-ci
Open

ci(docs): restore Documentation workflow (CPU runner) to fix stable docs#142
ChrisRackauckas wants to merge 1 commit into
mainfrom
restore-documentation-ci

Conversation

@ChrisRackauckas

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-pagesversions.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

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>
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