Add docs preview deployment and PR comment link to CI - #322
Draft
JohnGriffiths with Copilot wants to merge 2 commits into
Draft
JohnGriffiths with Copilot wants to merge 2 commits into
JohnGriffiths with Copilot wants to merge 2 commits into
Conversation
Co-authored-by: JohnGriffiths <397826+JohnGriffiths@users.noreply.github.com>
Copilot
AI
changed the title
[WIP] Add GitHub Actions for viewing built docs on CI
Add docs preview deployment and PR comment link to CI
Mar 19, 2026
JohnGriffiths
approved these changes
Mar 19, 2026
pellet
added a commit
to pellet/EEG-ExPy
that referenced
this pull request
Sep 27, 2026
…rtifact The cache stores `doc/_build/html`, which is not what makes a docs build cheap. 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` — neither cached, both gitignored, so every example re-executes every run. On master push [33301489918](https://github.com/NeuroTechX/EEG-ExPy/actions/runs/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 a `restore-keys` fallback 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.yml` otherwise only publishes on push to `master`. No change to the `master` deploy. Related: NeuroTechX#322 (draft) adds an artifact step too 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
added a commit
to pellet/EEG-ExPy
that referenced
this pull request
Sep 29, 2026
…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
added a commit
that referenced
this pull request
Sep 30, 2026
…rtifact (#337) 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: #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.
Collaborator
|
Now that #337 is merged, should we close this one? The live gh-pages preview only works for branches on this repo, because PRs from forks get a read-only token, so most contributors wouldn't get a preview. I'm not sure there's a good way to make a live preview work for forks. In the meantime, every docs CI run (forks included) uploads the built HTML as a |
This branch has not been deployed
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 docs workflow built documentation on every PR but provided no way to view the output. This adds PR preview deployments with an automatic bot comment linking to the live preview.
Changes to
.github/workflows/docs.ymltypes: [opened, synchronize, reopened, closed]— triggers cleanup when PRs closecontents: write(push togh-pages) andpull-requests: write(post PR comments)if: github.event.action != 'closed'— only cleanup runs on PR closedocs-{sha}artifact after each successful build, downloadable from the Actions runrossjrw/pr-preview-action@v1): Deploys built HTML togh-pages/pr-preview/pr-{number}/and posts a bot comment on the PR with the preview URLrossjrw/pr-preview-action@v1): Cleans up thegh-pagessubdirectory when the PR is closed/mergedThe existing master-branch deployment via
peaceiris/actions-gh-pagesis unchanged. Preview URLs follow the pattern:✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.