Clear the restored Sphinx environment before the publish build

.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: |