Repository navigation
fix(build-jupyter-cache): say when the jupyter repro command exits 0 on warnings (#311) - #321
Merged
Merged
Conversation
…on warnings (#311) When the jupyter build fails with -W and --keep-going in extra-args, the failure issue now says, under the commands to reproduce it, that the jupyter command exits 0 even when its build fails on warnings: sphinx-tojupyter's finish() calls exit() with 0 before Sphinx can fail the build, so only build-lectures' check of the warnings (#300) fails it in CI. The note names the WARNING:, ERROR: and CRITICAL: lines that check counts, and says that without --keep-going the build stops at the first warning and exits 1, which a local run with jupyter-book 1.0.4post1 and sphinx-tojupyter 0.6.0 confirmed. The commands keep the flags the build had. The two flags are read as build-lectures' check reads them: -W, a cluster such as -nW, or --warningiserror, with --keep-going. bjc-alert checks the notes exactly for each set of flags, with four new cases, and runs build-lectures' own loop on each case's extra-args to check that the two rules agree. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMbS8pHPqpX3c26k6pX
…-note Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMbS8pHPqpX3c26k6pX
Contributor
There was a problem hiding this comment.
Note
Copilot was unable to complete this review at the selected tier due to model policy or plan restrictions.
🟢 Approval recommended
The change is narrowly scoped and includes aligned flag parsing plus expanded fixture-based assertions (including cross-checking against the existing build-lectures loop) and corresponding documentation/changelog updates, with no outstanding issues indicated in the review evidence.
No open issues 🎉
What changed in this PR
Adjusts build-jupyter-cache failure issues so the suggested local jb build ... jupyter ... -W --keep-going repro doesn’t mislead maintainers when the command can still exit 0 on warning-driven failures.
Changes:
- Conditionally adds a
jupyter“exits 0 on warnings under-W --keep-going” explanatory note, with flag parsing aligned tobuild-lectures. - Expands the
bjc-alertfixture to assert exact note formatting and to cross-check the condition by runningbuild-lectures’ own flag-reading loop. - Updates workflow wiring plus user/dev docs and the changelog to reflect the new behavior.
| File | Description |
|---|---|
| docs/user/actions/build-jupyter-cache.md | Documents when the failure issue includes the extra jupyter note and how extra-args flags are interpreted. |
| docs/dev/TESTING.md | Updates the build-jupyter-cache testing coverage description to include the new conditional note behavior. |
| CHANGELOG.md | Adds an [Unreleased] → Fixed entry describing the clarified failure-issue text behavior. |
| build-jupyter-cache/action.yml | Updates the failure issue body generation to parse extra-args once and conditionally append the jupyter warning/exit-code note when -W/--warningiserror and --keep-going are both present. |
| .github/workflows/test-actions.yml | Passes the relevant build-lectures build-step script into the bjc-alert fixture so it can validate flag parsing against the source loop. |
| .github/fixtures/bjc-alert/test.cjs | Extends fixture parsing and assertions to capture post-command notes, adds cases for flag combinations, and validates the note condition by executing build-lectures’ guard loop. |
Review effort: Balanced
Merged
mmcky
added a commit
that referenced
this pull request
Nov 15, 2026
Cuts v0.20.1, a patch carrying #321: build-jupyter-cache's failure issue says when the jupyter repro command exits 0 on warnings (#311). v0 stays on v0.20.0 until the release gate has passed v0.20.1. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMbZoC2dpGt3sPyBjyd
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.
Why
When a
jupyterbuild fails, the issuebuild-jupyter-cachefiles gives a command to reproduce it locally. Under-W --keep-going, the defaultextra-args, that command exits 0 whatever the build warned about: sphinx-tojupyter'sfinish()callsexit()with 0 before Sphinx can fail the build (QuantEcon/sphinx-tojupyter#69).build-lecturesfails the build in CI on the warnings it logged (#307), but a maintainer who runs the command sees a green build and nothing to fix. This PR keeps the command as it is, matchingbuild-lectures' flags, and adds a note under it, only when the note applies. Closes #311.With the default flags and a failed
jupyterbuild, item 3 of the issue's Debug list now reads:(The command sits in a
bashblock in the real issue; the second paragraph is the one already there.)jupyterfailed,extra-argshas-W(or a cluster such as-nW, or--warningiserror) and--keep-goingjupyternotejupyterfailed,extra-argslacks-Wor--keep-going-Wa warning fails nothing, and-Walone exits 1 at the first warninghtmlorpdflatexfailedThe note names no issue or pull request. The issue is filed in the lecture repository, so a
#Nthere would point at that repository's own issues, and a fullQuantEcon/…#Nreference would add a cross-reference to that issue's timeline from every failure issue in every lecture repository.Changes
build-jupyter-cache/action.yml-Wand--keep-goingfromextra-argsasbuild-lectures' check does (build-lectures/action.yml:332-342):--warningiserrorand--keep-goingby name, any other--flag skipped, and a-flag with aWin it, such as-Wor-nW. The notes under the commands become a list: the error-output note always, thejupyternote whenjupyterfailed and both flags are there.extraArgsis split once and shared with the commands..github/fixtures/bjc-alert/test.cjsjupyternote follows (note:), and four new cases cover the flag reading:--keep-going -nWand--warningiserror --keep-going(note),--keep-goingalone and-Walone (no note). Each case also runsbuild-lectures' own loop (guardReads) on itsextra-args, and fails if the case'snote:disagrees with what that loop and thejupyterstatus give. 23 cases become 27..github/workflows/test-actions.ymlbjc-alert's Python passesbuild-lectures' build step's script to the fixture asguard. The job's comment covers the note. Nothing else in the harness changes.docs/user/actions/build-jupyter-cache.mddocs/dev/TESTING.mdbuild-jupyter-cache's row covers the note.CHANGELOG.md[Unreleased],### Fixed. Not breaking: only the issue's text changes.What I checked, and how
The issue check (
0fada07, by the organiser, posted on #311 as issuecomment-6889504734). Since #316, the commands are built fromnitpickandextra-args(build-jupyter-cache/action.yml:604-614before this PR), and with the defaults thejupyterone is the string #311 quotes. sphinx-tojupyter v0.6.0 still ends withexit(self.execution_status_code)(builders/jupyter.py:297), set to 0 at:48and never changed. I read the same lines in the 0.6.0 wheel I installed. The check's refinement holds: the note depends on the flags, sincebuild-lectures' check only applies under both-Wand--keep-going.The alternative, run locally. The note says that without
--keep-goingthe build stops at the first warning and exits 1.build-lectures' comment says so (:329), but no run was on record, so I ran one. I used a scratch venv withjupyter-book==1.0.4post1andsphinx-tojupyter==0.6.0, the full image's pins (Sphinx 7.4.7, myst-nb 1.4.0). The book was themini-lecturesfixture withextra_extensions: [sphinx_tojupyter], asbuild-jupyter-warning-guardsets it up. It had two pages that warn: that job'sbroken.md, whose cell raises (a warning while the pages are read), and a page with an undefined{ref}(a warning while they are written). Each build ran asjb build lectures --path-output <fresh dir> --builder=custom --custom-builder=jupyter <flags>:-n -W --keep-going-n -WSphinxWarning: …broken.md:Executing notebook failed: CellExecutionErrorWarning, treated as error: …badref.md:3:undefined label: 'no-such-label'-W,-nW,-n --warningiserror-n --keep-going,-nSo the last sentence of the note holds, for a warning from either phase. This is Sphinx 7: jupyter-book 1.0.4post1 requires
sphinx~=7.0, and both images take jupyter-book<2.0.The new assertions fail on today's code. I ran the branch's
test.cjsandbjc-alert's own Python onorigin/main's twoaction.ymlfiles. It exits 1, failing the five cases that expect the note: every builder failed;nitpick: 'false';extra-argsover two lines;--keep-going -nW;--warningiserror --keep-going. For each one, the expected notes and whatmaingives (the error-output note alone) are printed. The negative cases pass onmain, since it has no note. They are there to catch a note that shows up where it shouldn't, so I mutated the branch's code, once per rule:jupyter--keep-going-W-Wonly on its own, not in a clusterbuild-lectures' loop stops reading--warningiserrorOn the branch, all 27 cases pass. The run here, with Node 26, went through the same Python the job runs, taken from
test-actions.yml.Lint:
generate-docs.py --check --check-examples --actionlint(actionlint 1.7.12, its release checksum checked),actionlint, andscripts/lint-shell.py(shellcheck 0.11.0) are all clean. The CHANGELOG adds 14 lines and deletes none, and everything from## [0.20.0]down is byte-identical tomain.Callers. Only the issue's text changes. A code search in the org for
quantecon/actions/build-jupyter-cachefinds three workflows outside this repository: thecache.ymloflecture-dp,test-actions-lecture-introandtest-lecture-theme-sphinx. Each one calls the action and reads none of the issue's text.What to watch after merge
build-jupyter-cache/, so it merges on the organiser's word, and not during a lecture matrix run.build-lectures' check, andbjc-alertnow runs that check's loop frombuild-lectures/action.yml'sbuildstep. Its pattern is the linewarning_is_error=false keep_going=falsethrough thedoneat the same indent. If a change tobuild-lecturesmoves or rewrites that loop,bjc-alertfails and names it. Then update the alert's reading of the flags to match, not just the fixture.cache.ymlfiles no issue, so the note shows only when a cache build'sjupyterbuild fails.bjc-alertcovers its text.Not in this PR
build-lectures, or to its annotation's wording.--keep-goingfrom thejupytercommand was build-jupyter-cache: the failure issue's jupyter repro command exits 0 #311's other idea; the note mentions it instead, so the command still matches what CI ran.exit()infinish(), is upstream. Once a release lets Sphinx fail the build, both this note andbuild-lectures' check can go.-Wso that it no longer stops at the first warning. If a QuantEcon build ever moves to Sphinx 8, re-check the note's last sentence, andbuild-lectures' check, which looks only for-Wwith--keep-going. jupyter-book 1.x requires Sphinx 7.🤖 Generated with Claude Code
https://claude.ai/code/session_01WT8bMbS8pHPqpX3c26k6pX