Skip to content

ci: replace mkdocs-pr.yml with path-gated notebook-executing variant#189

Open
jonathanhhb wants to merge 1 commit into
mainfrom
ci/pr-notebook-execution
Open

ci: replace mkdocs-pr.yml with path-gated notebook-executing variant#189
jonathanhhb wants to merge 1 commit into
mainfrom
ci/pr-notebook-execution

Conversation

@jonathanhhb

Copy link
Copy Markdown
Collaborator

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.

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>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 in github-actions.yml and never executed notebooks).
  • Add mkdocs-pr-notebooks.yml that runs mkdocs build --config-file mkdocs.ci.yml with execute: true, gated to paths that can affect notebook execution.
  • Set timeout-minutes: 30 to 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.

@jonathanhhb

Copy link
Copy Markdown
Collaborator Author

Build failure will be fixed with #188.

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.

2 participants