QuantEcon / QuantEcon/actions

build-lectures: no `_build/.doctrees` clear (ipywidget mimetype rendering)

Open
#98 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug low-priority
Dominant language
Shell
Stars
0
Forks
1
Avg merge
32m
Merged PRs (30d)
3

Description

v0.8.0 validation study: two native pipelines clear the Sphinx doctree cache before the final HTML build to fix ipywidget mimetype rendering — lecture-python-intro (.github/workflows/publish.yml:90), lecture-python-advanced.myst (.github/workflows/publish.yml:91). Composite build-lectures has none: nothing here touches .doctrees; its pre-build HTML steps are only Stage PDF (build-lectures/action.yml:51) and Stage notebooks (build-lectures/action.yml:70).

Intra-job trigger, not a stale cache: jb writes one shared _build/.doctrees, so HTML in a three-format job reads doctrees from the earlier pdflatex and jupyter builds; reproduces cold. That pdflatex → jupyter → html sequence is the migration target (docs/MIGRATION-GUIDE.md:313-332); single-builder consumers like lecture-dp (builder: 'html') are out of scope. Unreproduced — inferred from the native BUG: comment.

No zero-build A/B — no clear-free repo emits widget output:

  • lecture-python-advanced.myst/lectures/matsuyama.md: sole ipywidgets import among migrated repos, cells skip-execution (no mimetype emitted), and that repo clears.

  • lecture-python-intro (also clears): executed rich output in markov_chains_I.md (HTML(anim.to_jshtml())) and inequality.md (plotly).

  • lecture-python-programming.myst: clear-free in production, but no executed widget/animation/plotly output.

  • QuantEcon/test-actions-lecture-intro: composite, no clear, no cache restore, but its canary TOC builds five rich-free lectures (geom_series, short_path, lln_clt, solow, linear_equations) under only_build_toc_files: true, unpublished since 2026-02-10; widening cuts against _toc.yml's no-content-drift criteria — separate decision.

  • Repro: build intro's markov_chains_I and inequality through the composite pdflatex → jupyter → html with no clear; compare to the published native site.

  • Matches → the clear is not load-bearing for current content; close wontfix with the negative result recorded.

  • Diverges → add an optional clear-doctrees input (default off) to the build-lectures HTML path, plus a MIGRATION-GUIDE note for repos coming from native pipelines.

  • Lower priority: the cache stores _build wholesale (restore-jupyter-cache/action.yml:109), so .doctrees rides along on restore — re-check once #92 Phase 1 turns on save-cache: 'true'.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with build-lectures/action.yml and the native workflow steps at .github/workflows/publish.yml:90-91. Reproduce the intro markov_chains_I and inequality builds through the pdflatex → jupyter → html sequence without clearing doctrees, then compare the output with the published native site. Done means recording a negative result for closure or documenting the divergence and updating the named migration and action paths.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions
Domain
build-system, ci-cd
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.