ci(docs): fix stale cache key and add a downloadable PR docs-build artifact - #337
Draft
pellet wants to merge 2 commits into
Draft
ci(docs): fix stale cache key and add a downloadable PR docs-build artifact#337pellet wants to merge 2 commits into
pellet wants to merge 2 commits into
Conversation
pellet
marked this pull request as draft
September 1, 2026 12:10
The doc build cache key only hashed examples/**/*.py, doc/**/*, and conf.py. A change to library code under eegnb/ (e.g. NeuroTechX#330) still counts as a 'full build' per the earlier changed-files check, but the cache step restores the same doc/_build/html as before since its key is unchanged, and sphinx-gallery skips re-running any example script that itself is unchanged. Net effect: CI can report success without ever re-rendering the affected example. Also there was no way to see a PR's doc build without checking it out and building locally - docs.yml only publishes to GitHub Pages on push to master. Upload the built HTML as a workflow artifact on every run so reviewers can download and open it directly from the PR's checks tab.
pellet
force-pushed
the
fix/docs-ci-cache-and-preview
branch
from
September 1, 2026 12:22
96ef0f4 to
2cab680
Compare
Widening the cache key is not sufficient on its own. `restore-keys:
${{ runner.os }}-sphinx-` prefix-matches the previous entry, so a miss on
the exact key still restores the old doc/_build/html, and sphinx-gallery
skips any example whose script hash matches the stamp in that restored
output. The build then reports green without re-rendering the example a
library change under eegnb/ actually affects.
Dropping restore-keys would close that but would also discard the
incremental case the "Determine build mode" step exists to serve: an
examples-only PR would rebuild every example from cold. So keep the
fallback and delete the restored HTML when FULL_BUILD=true - already the
workflow's own name for "something other than an example changed", and
the same flag doc/conf.py reads to widen sphinx-gallery's
filename_pattern.
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
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 doc-build cache key only hashes
examples/**/*.py,doc/**/*,conf.py. A change to library code undereegnb/(e.g. #330) still trips the "full build" changed-files check, but the cache step restores the samedoc/_build/htmlregardless — its key hasn't moved — and sphinx-gallery skips re-running any example script that's itself unchanged. Net effect: this CI can report green without ever re-rendering the example the library change actually affects.Widening the key isn't enough on its own.
restore-keys: ${{ runner.os }}-sphinx-prefix-matches the previous entry, so a miss on the exact key still restores the olddoc/_build/htmland sphinx-gallery still skips. Droppingrestore-keyswould close that, but it would also throw away the incremental case theDetermine build modestep exists to serve — an examples-only PR would then rebuild every example from cold. So this keeps the fallback and instead deletes the restored HTML whenFULL_BUILD=true, which is already the workflow's own name for "something other than an example changed", and is the same flagdoc/conf.pyreads to widen sphinx-gallery'sfilename_pattern. The wider cache key still earns its place: it keeps the saved entry trackingeegnb/instead of pinning it to a hash that ignores library code.Also: there's currently no way to see a PR's rendered docs short of checking it out and running
make docslocally —docs.ymlonly publishes to GitHub Pages on push tomaster. This addsactions/upload-artifactso every run's built HTML is downloadable from the PR's checks tab.No behavior change on
masterpushes (still deploys to Pages as before).Related: #322 (draft) also adds an
upload-artifactstep to this workflow and goes further, deploying a live rendered preview togh-pages/pr-preview/. This PR deliberately stops at the artifact: the preview push needs a write token, whichpull_requestruns from forks don't get, so a downloadable artifact is the part that works on every PR. The cache-key fix is orthogonal and isn't covered by #322.