Skip to content

ci(docs): fix stale cache key and add a downloadable PR docs-build artifact - #337

Draft
pellet wants to merge 2 commits into
NeuroTechX:masterfrom
pellet:fix/docs-ci-cache-and-preview
Draft

ci(docs): fix stale cache key and add a downloadable PR docs-build artifact#337
pellet wants to merge 2 commits into
NeuroTechX:masterfrom
pellet:fix/docs-ci-cache-and-preview

Conversation

@pellet

@pellet pellet commented Sep 1, 2026

Copy link
Copy Markdown
Collaborator

The doc-build cache key only hashes examples/**/*.py, doc/**/*, conf.py. A change to library code under eegnb/ (e.g. #330) still trips the "full build" changed-files check, but the cache step restores the same doc/_build/html regardless — 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 old doc/_build/html and sphinx-gallery still skips. Dropping restore-keys would close that, but it would also throw away the incremental case the Determine build mode step 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 when FULL_BUILD=true, which is already the workflow's own name for "something other than an example changed", and is the same flag doc/conf.py reads to widen sphinx-gallery's filename_pattern. The wider cache key still earns its place: it keeps the saved entry tracking eegnb/ 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 docs locally — docs.yml only publishes to GitHub Pages on push to master. This adds actions/upload-artifact so every run's built HTML is downloadable from the PR's checks tab.

No behavior change on master pushes (still deploys to Pages as before).

Related: #322 (draft) also adds an upload-artifact step to this workflow and goes further, deploying a live rendered preview to gh-pages/pr-preview/. This PR deliberately stops at the artifact: the preview push needs a write token, which pull_request runs 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.

@pellet
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
pellet force-pushed the fix/docs-ci-cache-and-preview branch from 96ef0f4 to 2cab680 Compare September 1, 2026 12:22
@pellet pellet changed the title ci(docs): fix stale cache key and add PR build artifact ci(docs): fix stale cache key and add a downloadable PR docs-build artifact Sep 1, 2026
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.
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