ci(docs): cache the gallery execution stamps, and publish a PR docs artifact - #337
Draft
pellet wants to merge 1 commit into
Draft
ci(docs): cache the gallery execution stamps, and publish a PR docs artifact#337pellet wants to merge 1 commit into
pellet wants to merge 1 commit into
Conversation
pellet
marked this pull request as draft
September 1, 2026 12:10
pellet
force-pushed
the
fix/docs-ci-cache-and-preview
branch
from
September 1, 2026 12:22
96ef0f4 to
2cab680
Compare
pellet
changed the title
Two independent changes to the docs workflow. 1. The cache never saved a rebuild. It stored doc/_build/html, but sphinx-gallery decides whether to re-run an example by comparing the example's md5 against `<example>.py.md5` written beside its generated rst in doc/auto_examples, and Sphinx tracks its own staleness in doc/_build/doctrees. Neither was cached, both are gitignored, so a fresh checkout had no stamps and every example re-executed every run: on the master push 33301489918 the cache hit restored 23 MB of html and the computation-time summary still reports 32.9 s, 31.3 s, 29.3 s and 24.2 s for the same examples. The restored html was overwritten and bought nothing. Cache doc/auto_examples and doc/_build/doctrees instead. Locally, a cold build takes 145 s and an immediate rebuild 28 s, with every previously executed example reported at 0.00 s; the one example that re-runs is the one that failed the first pass, since a failed example is never stamped. The key is in two parts because the per-example md5 covers only the example source and cannot see a library change. The prefix hashes eegnb/**, doc/** and the docs environment, and only the examples hash follows it, so a restore-key fallback can match only an entry built against the same library, an example-only change still reuses every other example's output, and a library change matches nothing and re-runs cold. This replaces a discard-on-full-build step: that keyed off a diff against master, which is empty on a master push, so it could not have caught the library merge it was meant to catch. 2. Upload doc/_build/html as an artifact so a reviewer can look at the rendered docs for a pull request. Deliberately not a deployed preview: that needs a write token, which pull_request runs from forks do not get, whereas a downloadable artifact works on every pull request.
pellet
force-pushed
the
fix/docs-ci-cache-and-preview
branch
from
September 3, 2026 12:34
312ec77 to
682e3c1
Compare
pellet
changed the title
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.
The cache stores
doc/_build/html, which is not what makes a docs build cheap. sphinx-gallery skips an example only when<example>.py.md5sits beside its generated rst indoc/auto_examples, and Sphinx tracks staleness indoc/_build/doctrees— neither cached, both gitignored, so every example re-executes every run. On master push 33301489918 the cache hit and the computation-time summary still shows 32.9 s, 31.3 s, 29.3 s, 24.2 s.Cache those two directories instead. Locally: cold build 145 s, rebuild 28 s, all previously executed examples at 0.00 s.
The key is two-part because the per-example md5 cannot see a library change. The prefix hashes
eegnb/**,doc/**and the docs environment; the examples hash follows it. So arestore-keysfallback only matches an entry built against the same library: examples-only PR reuses the rest, library change re-runs cold.Also adds
upload-artifact, so a reviewer can download a PR's rendered docs —docs.ymlotherwise only publishes on push tomaster. No change to themasterdeploy.Related: #322 (draft) adds an artifact step too and deploys a live preview to
gh-pages/pr-preview/; that push needs a write token, which forkpull_requestruns don't get, so the artifact is the part that works everywhere.