Skip to content

fix(build-jupyter-cache): say when the jupyter repro command exits 0 on warnings (#311) - #321

Merged
mmcky merged 2 commits into
mainfrom
fix/311-jupyter-repro-note
Nov 15, 2026
Merged

mmcky merged 2 commits into
mainfrom
fix/311-jupyter-repro-note

Conversation

@mmcky

@mmcky mmcky commented Nov 15, 2026

Copy link
Copy Markdown
Contributor

Why

When a jupyter build fails, the issue build-jupyter-cache files gives a command to reproduce it locally. Under -W --keep-going, the default extra-args, that command exits 0 whatever the build warned about: sphinx-tojupyter's finish() calls exit() with 0 before Sphinx can fail the build (QuantEcon/sphinx-tojupyter#69). build-lectures fails 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, matching build-lectures' flags, and adds a note under it, only when the note applies. Closes #311.

With the default flags and a failed jupyter build, item 3 of the issue's Debug list now reads:

  1. Reproduce locally: jb build lectures --path-output . --builder=custom --custom-builder=jupyter -n -W --keep-going

    A build that failed only on error outputs passes jb build: its log names each notebook and cell whose traceback the page shows.

    The jupyter command also exits 0 when its build fails on warnings: with these flags, sphinx-tojupyter ends the build before Sphinx can fail it. build-lectures fails it instead, on the WARNING:, ERROR: and CRITICAL: lines it prints, and lists them in the run's log. Without --keep-going, the build stops at the first warning and exits 1.

(The command sits in a bash block in the real issue; the second paragraph is the one already there.)

A failed run's issue Before After
jupyter failed, extra-args has -W (or a cluster such as -nW, or --warningiserror) and --keep-going The commands, and the error-output note The same, then the jupyter note
jupyter failed, extra-args lacks -W or --keep-going The commands, and the error-output note Unchanged: without -W a warning fails nothing, and -W alone exits 1 at the first warning
Only html or pdflatex failed The commands, and the error-output note Unchanged

The note names no issue or pull request. The issue is filed in the lecture repository, so a #N there would point at that repository's own issues, and a full QuantEcon/…#N reference would add a cross-reference to that issue's timeline from every failure issue in every lecture repository.

Changes

File Change
build-jupyter-cache/action.yml The alert script reads -W and --keep-going from extra-args as build-lectures' check does (build-lectures/action.yml:332-342): --warningiserror and --keep-going by name, any other -- flag skipped, and a - flag with a W in it, such as -W or -nW. The notes under the commands become a list: the error-output note always, the jupyter note when jupyter failed and both flags are there. extraArgs is split once and shared with the commands.
.github/fixtures/bjc-alert/test.cjs The "Reproduce locally" match now captures the notes after the block too, and each case checks them exactly, indentation included. Each case says whether the jupyter note follows (note:), and four new cases cover the flag reading: --keep-going -nW and --warningiserror --keep-going (note), --keep-going alone and -W alone (no note). Each case also runs build-lectures' own loop (guardReads) on its extra-args, and fails if the case's note: disagrees with what that loop and the jupyter status give. 23 cases become 27.
.github/workflows/test-actions.yml bjc-alert's Python passes build-lectures' build step's script to the fixture as guard. The job's comment covers the note. Nothing else in the harness changes.
docs/user/actions/build-jupyter-cache.md "When a build fails", item 3, says when the issue adds the note, and how it reads the flags.
docs/dev/TESTING.md build-jupyter-cache's row covers the note.
CHANGELOG.md One entry under [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 from nitpick and extra-args (build-jupyter-cache/action.yml:604-614 before this PR), and with the defaults the jupyter one is the string #311 quotes. sphinx-tojupyter v0.6.0 still ends with exit(self.execution_status_code) (builders/jupyter.py:297), set to 0 at :48 and 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, since build-lectures' check only applies under both -W and --keep-going.

The alternative, run locally. The note says that without --keep-going the 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 with jupyter-book==1.0.4post1 and sphinx-tojupyter==0.6.0, the full image's pins (Sphinx 7.4.7, myst-nb 1.4.0). The book was the mini-lectures fixture with extra_extensions: [sphinx_tojupyter], as build-jupyter-warning-guard sets it up. It had two pages that warn: that job's broken.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 as jb build lectures --path-output <fresh dir> --builder=custom --custom-builder=jupyter <flags>:

Flags Both pages The bad reference alone
-n -W --keep-going exit 0, 3 warnings exit 0, 1 warning
-n -W exit 1: SphinxWarning: …broken.md:Executing notebook failed: CellExecutionError exit 1: Warning, treated as error: …badref.md:3:undefined label: 'no-such-label'
-W, -nW, -n --warningiserror exit 1, the same exit 1, the same
-n --keep-going, -n exit 0, 3 warnings exit 0, 1 warning

So 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.cjs and bjc-alert's own Python on origin/main's two action.yml files. It exits 1, failing the five cases that expect the note: every builder failed; nitpick: 'false'; extra-args over two lines; --keep-going -nW; --warningiserror --keep-going. For each one, the expected notes and what main gives (the error-output note alone) are printed. The negative cases pass on main, 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:

Mutation Fails
The note for any failed builder, not only jupyter "html failed…", "pdflatex failed…"
The note without checking --keep-going "with -W and no --keep-going"
The note without checking -W "with --keep-going and no -W"
-W only on its own, not in a cluster "-nW"
build-lectures' loop stops reading --warningiserror "--warningiserror and --keep-going", with "build-lectures' check reads -W/--keep-going as [false/true]"

On 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, and scripts/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 to main.

Callers. Only the issue's text changes. A code search in the org for quantecon/actions/build-jupyter-cache finds three workflows outside this repository: the cache.yml of lecture-dp, test-actions-lecture-intro and test-lecture-theme-sphinx. Each one calls the action and reads none of the issue's text.

What to watch after merge

  • This touches build-jupyter-cache/, so it merges on the organiser's word, and not during a lecture matrix run.
  • The note follows build-lectures' check, and bjc-alert now runs that check's loop from build-lectures/action.yml's build step. Its pattern is the line warning_is_error=false keep_going=false through the done at the same indent. If a change to build-lectures moves or rewrites that loop, bjc-alert fails and names it. Then update the alert's reading of the flags to match, not just the fixture.
  • For the canary at release: nothing new to exercise. A passing cache.yml files no issue, so the note shows only when a cache build's jupyter build fails. bjc-alert covers its text.

Not in this PR

🤖 Generated with Claude Code

https://claude.ai/code/session_01WT8bMbS8pHPqpX3c26k6pX

mmcky and others added 2 commits November 15, 2026 16:17
…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
Copilot AI balanced review requested due to automatic review settings November 15, 2026 05:19

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.

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 to build-lectures.
  • Expands the bjc-alert fixture to assert exact note formatting and to cross-check the condition by running build-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

@mmcky
mmcky merged commit 48573a2 into main Nov 15, 2026
73 checks passed
@mmcky
mmcky deleted the fix/311-jupyter-repro-note branch November 15, 2026 05:29
@mmcky mmcky mentioned this pull request Nov 15, 2026
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
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.

build-jupyter-cache: the failure issue's jupyter repro command exits 0

2 participants