Skip to content

ci(docs): cache the gallery execution stamps, and publish a PR docs artifact - #337

Merged
pellet merged 1 commit into
NeuroTechX:masterfrom
pellet:fix/docs-ci-cache-and-preview
Sep 30, 2026
Merged

pellet merged 1 commit into
NeuroTechX:masterfrom
pellet:fix/docs-ci-cache-and-preview

Conversation

@pellet

@pellet pellet commented Sep 1, 2026 •

Copy link
Copy Markdown
Collaborator

The cache stores doc/_build/html, which does not make a docs build cheaper. sphinx-gallery skips an example only when <example>.py.md5 sits beside its generated rst in doc/auto_examples, and Sphinx tracks staleness in doc/_build/doctrees. The current cache holds neither directory, so every example re-executes on every run. On master push 33301489918 the cache hit, yet the examples still took 155 s to execute in total.

Cache those two directories instead, so unchanged examples are skipped. Locally, a build drops from 145 s (every run today) to 28 s when no example changed.

The key has two parts because each example's md5 covers only that example's file, so it is not affected by changes to the library, docs sources or docs environment. The prefix hashes eegnb/**, doc/**, the docs environment, requirements.txt and setup.py; the examples hash follows. A restore-keys fallback therefore only matches an entry built with the same prefix: an examples-only PR reuses the other examples' output, and a change to any file in the prefix triggers a full rebuild.

Also adds upload-artifact, so reviewers can download a PR's rendered docs; docs.yml otherwise only publishes on push to master. The master deploy is unchanged.

Related: #322 (draft) also adds an artifact step and deploys a live preview to gh-pages/pr-preview/. That push needs a write token, which fork pull_request runs don't get, so the artifact is the part that works everywhere.

@pellet
pellet marked this pull request as draft September 1, 2026 12:10
@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
@pellet
pellet force-pushed the fix/docs-ci-cache-and-preview branch from 312ec77 to 682e3c1 Compare September 3, 2026 12:34
@pellet pellet changed the title ci(docs): fix stale cache key and add a downloadable PR docs-build artifact ci(docs): cache the gallery execution stamps, and publish a PR docs artifact Sep 3, 2026
@pellet
pellet force-pushed the fix/docs-ci-cache-and-preview branch from 452992b to 00f899c Compare September 27, 2026 08:42
…rtifact

The cache stores `doc/_build/html`, which does not make a docs build cheaper. sphinx-gallery skips an example only when `<example>.py.md5` sits beside its generated rst in `doc/auto_examples`, and Sphinx tracks staleness in `doc/_build/doctrees`. The current cache holds neither directory, so every example re-executes on every run. On master push [33301489918](https://github.com/NeuroTechX/EEG-ExPy/actions/runs/33301489918/attempts/1) the cache hit, yet the examples still took 155 s to execute in total.

Cache those two directories instead, so unchanged examples are skipped. Locally, a build drops from 145 s (every run today) to 28 s when no example changed.

The key has two parts because each example's md5 covers only that example's file, so it is not affected by changes to the library, docs sources or docs environment. The prefix hashes `eegnb/**`, `doc/**`, the docs environment, `requirements.txt` and `setup.py`; the examples hash follows. A `restore-keys` fallback therefore only matches an entry built with the same prefix: an examples-only PR reuses the other examples' output, and a change to any file in the prefix triggers a full rebuild.

Also adds `upload-artifact`, so reviewers can download a PR's rendered docs; `docs.yml` otherwise only publishes on push to `master`. The `master` deploy is unchanged.

Related: NeuroTechX#322 (draft) also adds an artifact step and deploys a live preview to `gh-pages/pr-preview/`. That push needs a write token, which fork `pull_request` runs don't get, so the artifact is the part that works everywhere.
@pellet
pellet force-pushed the fix/docs-ci-cache-and-preview branch from 00f899c to 8e2d1db Compare September 29, 2026 13:37
@pellet
pellet marked this pull request as ready for review September 30, 2026 21:51
@pellet
pellet merged commit ae03740 into NeuroTechX:master Sep 30, 2026
8 checks passed
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