Clear the restored Sphinx environment before the publish build

[mmcky]

Closes #270.

What was wrong

publish.yml unpacks the cache.yml artifact into _build whole — including _build/.doctrees, the Sphinx environment from the run that produced the artifact — and never clears it. That environment is not per-page state; it holds cross-document state, principally the resolved toctree and the section numbering derived from it. Reusing it means every page renders its navigation from the table of contents as it stood when the artifact was built, however current the sources are.

Important correction to the issue as filed. #270 says publish deployed stale HTML for pages it did not rebuild. That is not what happened, and I have corrected the issue. The build rewrote all 145 documents from the tagged sources — the run log's HTML phase shows writing output for 145 docnames including career, mccall_persist_trans and mccall_risk. The pages are fresh; the global state they were rendered against is stale. The reader-visible symptoms in #270 are all real, the fix is the same, but the mechanism is different and worth stating correctly.

Evidence

The artifact in use was from 2026-08-17, because the three cache.yml runs since then had failed. mccall_risk entered _toc.yml on 2026-08-21 with #264, so the restored environment had never seen it. In the release asset for publish-2026aug24 — the build's own output, so this is not a deploy or CDN artefact — the Search section of career.html's navigation reads: mccall_model, mccall_model_with_separation, mccall_model_with_sep_markov, mccall_fitted_vfi, mccall_persist_trans, jv, odu. mccall_risk is absent, though it sits between mccall_fitted_vfi and mccall_persist_trans in _toc.yml at the published commit and its own page was built and deployed. The same omission appears on mccall_persist_trans.html.

Numbering follows from the same stale toctree, one behind from mccall_persist_trans onward, which is why two lectures publish under the same chapter number:

Page	<title> as published	Expected from _toc.yml
mccall_risk.html	57. 工作搜寻 V：风险敏感型偏好	57
mccall_persist_trans.html	57. 工作搜寻 V：持续性与暂时性工资冲击	58
career.html	58. 工作搜寻 VI：职业选择建模	59

There were no toctree warnings in the build, and _toc.yml at 37d8e85 is correct and lists mccall_risk exactly once — the sources were never the problem.

The change

One step after the artifact download, dropping .doctrees and html from the restored tree and keeping .jupyter_cache, which is the expensive notebook execution and the only part the artifact exists to supply. ci.yml has carried exactly this step ("Clear stale Sphinx environment") since it was added; publish.yml had it only as a commented-out line next to the HTML build. The stale comment there is replaced with a pointer to the new step.

_build/html is dropped alongside the doctrees so that output for a lecture removed from the table of contents cannot survive in the deploy. The removal sits before "Copy Download Notebooks for GH-PAGES", which recreates _build/html/_notebooks, so the download-notebook assets are unaffected.

The cost is a Sphinx render, not a re-execution — notebook execution still comes from the cache.

Verifying this

Merging alone changes nothing already published; the fix takes effect at the next publish. The re-cut that #270 needs is the verification: after a green cache.yml run, tag and then confirm that career.html lists mccall_risk in its navigation and that no two lectures share a chapter number. A cache run was dispatched on main on 2026-08-24 and gates that re-cut.

Worth noting for whoever reviews the re-published site: this fix does not address #266, the duplicated Roman numeral V on those same two lectures. That is a source-content defect — the five undelivered upstream renumberings — and it will still be there after a clean rebuild.

Why this was invisible

Every signal was green. The workflow succeeded, all 145 pages return HTTP 200, check-tofu --site reports no missing glyphs, and no link 404s. The defect exists only in cross-page consistency, which nothing currently checks. Related: #271 covers the cache.yml gate defects that let the artifact go stale in the first place.

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for astonishing-narwhal-a8fc64 ready!

Name	Link
🔨 Latest commit	5e0b9c0
🔍 Latest deploy log	https://app.netlify.com/projects/astonishing-narwhal-a8fc64/deploys/6a8c0fd61f55de00084ae075
😎 Deploy Preview	https://deploy-preview-272--astonishing-narwhal-a8fc64.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Copilot]

Pull request overview

Updates the publish workflow to avoid reusing a cached Sphinx environment restored from the build-cache artifact, ensuring the published site’s navigation and section numbering are generated from the current _toc.yml and sources.

Changes:

• Add a “Clear stale Sphinx environment” step to delete _build/.doctrees and _build/html after downloading the cache artifact (preserving the notebook execution cache).
• Replace the outdated commented guidance near the HTML build with an explanation that the environment is cleared earlier.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

🚀 Deployed on https://6a8c2039b14d3abd8a574124--astonishing-narwhal-a8fc64.netlify.app