From 6f302c55f404331e3f462aba3f15735b97c7b70f Mon Sep 17 00:00:00 2001 From: Matt McKay Date: Mon, 24 Aug 2026 19:21:56 +1000 Subject: [PATCH 1/2] Clear the restored Sphinx environment before the publish build MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit publish.yml unpacks the cache.yml artifact into _build whole — including the .doctrees Sphinx environment from the run that produced it — and never clears it. That environment holds cross-document state: the resolved toctree and the section numbering derived from it. Reusing it makes every page render its navigation from the table of contents as it stood when the artifact was built, however current the sources are. publish-2026aug24 shipped that. Its build rewrote all 145 documents from the tagged sources, but against an environment restored from 2026-08-17, which predates mccall_risk entering _toc.yml. The published output has mccall_risk missing from the navigation of every other page, and the section numbering one behind from mccall_persist_trans onward, so mccall_risk and mccall_persist_trans both publish as chapter 57. Drop .doctrees and html from the restored tree, keeping .jupyter_cache — the expensive notebook execution and the only part the artifact is for. ci.yml has carried the same step since it was added; publish.yml had it only as a commented-out line. Closes #270 Co-Authored-By: Claude Opus 5 (1M context) --- .github/workflows/publish.yml | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 5685ef15..a3130d67 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -47,6 +47,17 @@ jobs: branch: main name: build-cache path: _build + # The artifact is a whole `_build` tree, including the Sphinx environment + # (`.doctrees`) from the run that produced it. That environment holds + # cross-document state — the resolved toctree, and the section numbering + # derived from it — so reusing it makes every page render its navigation + # from the table of contents as it stood when the artifact was built, no + # matter how current the sources are. The part worth keeping is + # `.jupyter_cache`, which is the expensive notebook execution. + # `ci.yml` already does this; see issue #270. + - name: Clear stale Sphinx environment + shell: bash -l {0} + run: rm -rf _build/.doctrees _build/html # # Build Assets (Download Notebooks and PDF via LaTeX) # - name: Build PDF from LaTeX # shell: bash -l {0} @@ -67,9 +78,8 @@ jobs: mkdir -p _build/html/_notebooks cp -u _build/jupyter/*.ipynb _build/html/_notebooks # Build HTML (Website) - # BUG: rm .doctress to remove `sphinx` rendering issues for ipywidget mimetypes - # and clear the sphinx cache for building final HTML documents. - # # rm -r _build/.doctrees + # The Sphinx environment restored from the cache artifact is cleared right + # after the download, above, so this build reads every source afresh. - name: Build HTML shell: bash -l {0} run: | From 5e0b9c0ec6f9b7f524d7da682bd88743455ec146 Mon Sep 17 00:00:00 2001 From: Matt McKay Date: Mon, 24 Aug 2026 19:33:05 +1000 Subject: [PATCH 2/2] Qualify the cache paths in the publish workflow comment Name `_build/.doctrees` and `_build/.jupyter_cache` in full, matching the paths the step's own `run:` line uses, so a reader debugging the step does not have to carry the `_build` prefix down from an earlier sentence. Comment text only; no change in behaviour. Co-Authored-By: Claude Opus 5 (1M context) --- .github/workflows/publish.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index a3130d67..03784a1f 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -48,12 +48,12 @@ jobs: name: build-cache path: _build # The artifact is a whole `_build` tree, including the Sphinx environment - # (`.doctrees`) from the run that produced it. That environment holds + # (`_build/.doctrees`) from the run that produced it. That environment holds # cross-document state — the resolved toctree, and the section numbering # derived from it — so reusing it makes every page render its navigation # from the table of contents as it stood when the artifact was built, no # matter how current the sources are. The part worth keeping is - # `.jupyter_cache`, which is the expensive notebook execution. + # `_build/.jupyter_cache`, which is the expensive notebook execution. # `ci.yml` already does this; see issue #270. - name: Clear stale Sphinx environment shell: bash -l {0}