docs: serve Pages from docs-store branch; fix #291 versioned-docs deploy - #292
Merged
Conversation
…b output (#291) The versioned-docs Pages deploy silently skipped for the v3.0.0 release: build_docs ran relver (is_release=true), pushed the docs-store branch, and uploaded the Pages artifact -- yet deploy_docs, gated on `needs.build_docs.outputs.is_release == 'true'`, was skipped. In a reusable-workflow context that cross-job output did not propagate into the downstream job `if`, even though the producing job logged "Set output". Drop the fragile job output. deploy_docs now runs on `needs.build_docs.result == 'success' && inputs.deploy` (both terms proven true in the failed run) and re-derives is_release locally from VERSION, gating only the actual deploy-pages step. Immune to the propagation quirk; for prereleases build_docs uploads no artifact so the deploy step no-ops green, never clobbering the multi-version site. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A minimal workflow that publishes the durable docs-store branch straight to Pages without rebuilding docs -- for (re)publishing the site or recovering a deploy that failed only at the Pages step. Also a fast 2-min probe of actions/deploy-pages in isolation. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Root fix for #291: instead of deploying the versioned docs via actions/deploy-pages (which failed structurally with Azure BlobNotFound on the ~140MB store, even though the artifact was valid and downloadable), serve GitHub Pages DIRECTLY from the docs-store branch. Pushing the store IS the deploy now -- no artifact exchange, nothing to skip, no cross-job output to propagate. v3.0.0 is live on bertini2.org. Also slim what gets published: - /stable/ becomes a tiny redirect stub to the newest /vX.Y.Z/ instead of a 69MB byte-for-byte copy (halves the store, halves the file count). - .doctrees Sphinx caches are dropped -- at the source via `sphinx-build -d`, and as defense-in-depth in the assembler's copy (~13MB of pure junk gone). - assembler writes /CNAME (--cname) so branch-source Pages keeps the bertini2.org custom domain across builds. Workflow: remove the upload-pages-artifact step and the entire deploy_docs job; drop now-unused pages:/id-token: perms from publish.yml's docs caller; delete the throwaway deploy_docs_store.yml. assemble_versioned_docs tests updated (stable is now a redirect; .doctrees dropped; CNAME emission). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Carries the edits that the prior commit's message described but did not contain (an aborted `git add` staged only the file deletion): - build_docs.yml: sphinx-build -d (drop .doctrees), assemble --cname bertini2.org, remove upload-pages-artifact + the entire deploy_docs job (branch-source Pages publishes on push to docs-store). - publish.yml: drop now-unused pages:/id-token: from the docs caller. - assemble_versioned_docs.py: /stable/ redirect stub (not a copy), .doctrees ignored on copy, --cname writes /CNAME; tests updated (14 pass). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…-pages (#291) Records why versioned-docs publishing serves the docs-store branch directly instead of actions/deploy-pages (structural BlobNotFound on the ~140MB store), the custom-domain-via-CNAME-file consequence, and the stable-redirect / .doctrees-drop slimming. Guards against a well-meaning switch back. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
ofloveandhate
added a commit
that referenced
this pull request
Jul 9, 2026
The changelog had drifted badly: the last entry was **2.0.1**, while **2.0.2**, the entire **3.0.0** modernization, and the **3.1.0** line had all shipped — with their notes living only in commit messages, PRs, and GitHub Releases. This consolidates them back into `CHANGELOG.md`, newest-first, in the existing *Keep a Changelog* format. ### New entries - **[3.1.0] – 2026-07-09** — NumPy interop for the mp dtypes (#306), the Python UI quality-of-life batch (#293–#304, #305), `ZeroDimConfig.recall` (#308), prebuilt CI deps (ADR-0049, #282), and docs-store Pages (ADR-0050, #291, #292). - **[3.0.0] – 2026-07-07** — reworked from the hand-written v3.0.0 release notes (~70 PRs; full themed index in #238) into Added / Changed / Fixed sections. - **[2.0.2] – 2026-05-22** — the packaging/CI maintenance entry that was never recorded. Older 1.0.x / 2.0.1 entries and the commented template are untouched. ### Why now (load-bearing) `publish.yml`'s `github-release` job builds the release body from the **top** `CHANGELOG.md` block. That block was the stale **[2.0.1]** — so a final `v3.1.0` tag would have published 2.0.1's notes as the 3.1.0 release. With this merged, the extraction yields exactly the **[3.1.0]** block (verified locally against the workflow's extraction logic). Docs-only (`**/*.md` → `paths-ignore`), so this runs no CI. **Merge before tagging `v3.1.0`.**
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #291 — versioned docs now deploy (and can't hit
BlobNotFound)Symptom: the v3.0.0 versioned docs built and the
docs-storebranch was pushed, but the GitHub Pages deploy never published.What I found:
deploy_docsgate depended on a cross-job output (needs.build_docs.outputs.is_release) that didn't propagate into the downstreamifin the reusable-workflow context — the job skipped despite the artifact being uploaded and the output being set.actions/deploy-pagesthen failed structurally with an AzureBlobNotFoundon the ~140 MB store — reproducibly, across re-runs — even though thegithub-pagesartifact was valid and downloadable via the normal API. The Actions→Pages artifact-exchange, not our content, was the problem.The fix — stop deploying Pages from an Actions artifact; serve it directly from the
docs-storebranch.docs-store//(a settings change, with@ofloveandhate's OK). Pushing the store is the deploy — no artifact exchange, nothing to skip, no cross-job output. v3.0.0 is live on bertini2.org.upload-pages-artifactstep and the entiredeploy_docsjob; dropped now-unusedpages:/id-token:perms frompublish.yml's docs caller; deleted the throwawaydeploy_docs_store.yml./CNAME(assembler--cname, plus a file on the branch) so branch-source Pages keeps thebertini2.orgdomain across builds.Also slimmed the published store (173 MB → 86 MB, 9589 → 4597 files):
/stable/is now a tiny redirect stub to the newest/vX.Y.Z/instead of a 69 MB byte-for-byte copy..doctreesSphinx caches are dropped — at the source (sphinx-build -d) and defensively in the assembler copy.assemble_versioned_docstests updated (stable-is-a-redirect,.doctreesdropped, CNAME emission) — 14 pass.Docs-update workflow this enables
build_docs(dispatch) → it assembles intodocs-storeand pushes → Pages republishes. No release, no PyPI, no full matrix.docs-store.