diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 5685ef15..03784a1f 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 + # (`_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 + # `_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} + 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: |