ci: replace mkdocs-pr.yml with path-gated notebook-executing variant#189
Open
jonathanhhb wants to merge 1 commit into
Open
ci: replace mkdocs-pr.yml with path-gated notebook-executing variant#189jonathanhhb wants to merge 1 commit into
jonathanhhb wants to merge 1 commit into
Conversation
Before: two PR-time docs builds, both with mkdocs-jupyter execute=false.
- github-actions.yml's "docs" matrix entry (tox -e docs → mkdocs build)
- mkdocs-pr.yml ("MkDocs Build on PR" → mkdocs build)
Neither caught a broken notebook because the static mkdocs-jupyter
render doesn't actually run the cells; notebooks were only executed at
manual release time (release-publish.yml's docs-deploy job via
mkdocs.ci.yml).
After:
- github-actions.yml's "docs" matrix entry stays as-is — fast,
runs on every PR, catches mkdocs config breakage.
- mkdocs-pr.yml is deleted (it was duplicate work).
- New mkdocs-pr-notebooks.yml runs `mkdocs build --config-file
mkdocs.ci.yml` (mkdocs-jupyter execute=true, allow_errors=false),
gated to PRs that touch:
* docs/tutorials/notebooks/** — notebooks themselves
* mkdocs.ci.yml / mkdocs.yml — config that affects execution
* docs/requirements.txt — runtime deps
* pyproject.toml — laser-generic deps/version
* src/** — package code notebooks import
* the workflow itself — so editing it self-tests
Cost: PRs that touch any of those paths pay the notebook-execution
runtime (currently ~15 min total, dominated by nb 06's ~8 min sim);
PRs that touch only unrelated code (sphinx, tests, other CI, README)
skip the heavy job entirely.
timeout-minutes: 30 leaves headroom; bump when longer notebooks land.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Replaces the duplicate, non-executing PR docs build (mkdocs-pr.yml) with a path-gated workflow (mkdocs-pr-notebooks.yml) that actually executes notebooks via mkdocs.ci.yml, so broken tutorial notebooks are caught at PR time instead of only at release.
Changes:
- Delete
mkdocs-pr.yml(it duplicated the fast docs build already ingithub-actions.ymland never executed notebooks). - Add
mkdocs-pr-notebooks.ymlthat runsmkdocs build --config-file mkdocs.ci.ymlwithexecute: true, gated to paths that can affect notebook execution. - Set
timeout-minutes: 30to accommodate the current ~15 min notebook execution runtime.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| .github/workflows/mkdocs-pr.yml | Removes the redundant non-executing PR docs build. |
| .github/workflows/mkdocs-pr-notebooks.yml | New path-gated workflow that builds docs with notebook execution enabled. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Collaborator
Author
|
Build failure will be fixed with #188. |
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.
Before: two PR-time docs builds, both with mkdocs-jupyter execute=false.
After:
mkdocs build --config-file mkdocs.ci.yml(mkdocs-jupyter execute=true, allow_errors=false), gated to PRs that touch:Cost: PRs that touch any of those paths pay the notebook-execution runtime (currently ~15 min total, dominated by nb 06's ~8 min sim); PRs that touch only unrelated code (sphinx, tests, other CI, README) skip the heavy job entirely.
timeout-minutes: 30 leaves headroom; bump when longer notebooks land.