ci(publish): clear cached HTML so the publish build renders current sources

[mmcky]

The publish-2026oct09 run succeeded but deployed the build cache from 5 October unchanged, so python.quantecon.org does not show the lectures merged in #1078. Three pieces of evidence:

• The run's "Build HTML" step logged "updating environment: 0 added, 0 changed, 0 removed", "looking for now-outdated files... none found", and then "no targets are out of date", so it wrote no pages.
• The release's own lecture-python-html-publish-2026oct09.tar.gz contains an ak2.html without the new content.
• The live ak2, ak_aiyagari and two_computation pages have none of the new exercises or labels, although their last-modified header is the deploy time.

The mechanism is in Sphinx's HTML builder: a page is rewritten only when its source file is newer than the existing output file. The cache artifact is extracted into _build after the checkout, so every cached HTML file carries a later mtime than every source and nothing is considered outdated. The earlier PDF and notebook builders consume the environment update, which is why the HTML step also sees zero changed documents.

This adds a step after the cache download that removes _build/html and _build/.doctrees, so the HTML build renders every page from the current sources. ci.yml already removes .doctrees at the same point. Executed notebook outputs are kept in _build/.jupyter_cache, so the extra cost is the HTML render only.

After this merges, #1078 needs a fresh publish tag to go live, and #1082 should merge first so that tag's PDF build passes.

🤖 Generated with Claude Code

[Copilot]

🟢 Approval recommended

The single-line workflow step correctly removes only regenerated build artifacts, is consistent with the existing ci.yml cleanup, and subsequent steps recreate the deleted directories, so the fix is low-risk with no identified issues.

0 open findings

What changed in this PR

This PR fixes a publishing bug where the publish* tag workflow deployed stale HTML. The build-cache artifact (produced by cache.yml) contains the entire _build directory — including _build/html and _build/.doctrees — and is extracted into _build after the checkout. Because the cached HTML files then carry a newer mtime than every freshly checked-out source file, Sphinx's HTML builder considers nothing out of date ("no targets are out of date") and rewrites no pages, so merged content (e.g. from #1078) never reaches python.quantecon.org. The fix adds a step that deletes _build/html and _build/.doctrees after the cache download, forcing a full HTML render from current sources while keeping the executed-notebook cache in _build/.jupyter_cache.

I confirmed the fix is safe: the removal runs before any step populates _build/html, and the later "Copy LaTeX PDF" and "Copy Download Notebooks" steps recreate _build/html/_pdf and _build/html/_notebooks via mkdir -p. The approach mirrors the existing .doctrees cleanup in ci.yml, and the surrounding PDF/notebook builds already run full -n -W builds, so the full HTML re-render surfaces no new failures.

Changes:

• Add a "Clear cached HTML and stale Sphinx environment" step after the cache download that runs rm -rf _build/html _build/.doctrees.
• Add an explanatory comment documenting the mtime mechanism and that executed notebook outputs are preserved.

File	Description
.github/​workflows/​publish.yml	Adds a post-cache-download step removing stale cached HTML and the pickled Sphinx environment so the publish HTML build renders every page from current sources.

🧠 Review effort: Balanced

---

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

[github-actions]

📖 Netlify Preview Ready!

Preview URL: https://pr-1083--sunny-cactus-210e3e.netlify.app

Commit: e7e0bc6

---

Build Info

• Workflow: Build Project [using jupyter-book]