Migrate to Jupyter Book 2

.github/workflows/publish.yml

@@ -42,8 +42,6 @@ jobs:
       #     path: ./
       - name: Render for school
         run: ./extras/scripts/school_ci.sh ${{ matrix.school }}
-      - name: Fix double-escaping
-        run: make fix_double_escaping
       - name: Update commit
         run: |
           git add -A

.gitignore

@@ -6,7 +6,6 @@ _build/
 *.csv
 *.slides.html
 * threads.json
-conf.py
 data
 shared
 solutions

.readthedocs.yaml

@@ -7,16 +7,21 @@ python:
       command: sync
 
 build:
-  os: ubuntu-lts-latest
+  os: ubuntu-24.04
   tools:
-    python: "3"
+    python: "3.12"
+    nodejs: "22"
   jobs:
-    # https://jupyterbook.org/en/stable/publish/readthedocs.html
-    pre_build:
-      - jupyter-book config sphinx .
-    post_build:
-      - make fix_double_escaping build_dir="$READTHEDOCS_OUTPUT"
-
-sphinx:
-  # https://about.readthedocs.com/blog/2024/12/deprecate-config-files-without-sphinx-or-mkdocs-config/
-  configuration: conf.py
+    # https://docs.readthedocs.com/platform/stable/build-customization.html#override-the-build-process
+    build:
+      html:
+        # serve assets/links from the version's path, e.g. /en/columbia
+        - BASE_URL="$(echo "$READTHEDOCS_CANONICAL_URL" | sed -E 's|^https?://[^/]+||; s|/$||')" make site
+        - >-
+          uv run --with click --with pyyaml
+          https://raw.githubusercontent.com/jupyter-book/jb1-redirect-generator/d70ce6d7df9f2dfc83bb1d409336c0cc3e20697f/generate_redirects.py
+          --base-url "$READTHEDOCS_CANONICAL_URL"
+          --output-dir _build/html
+          --myst-config myst.yml
+        - mkdir -p "$READTHEDOCS_OUTPUT/html/"
+        - cp -r _build/html/. "$READTHEDOCS_OUTPUT/html"

Makefile

@@ -21,9 +21,10 @@ file := .
 format:
 	ruff format $(file)
 
-# https://jupyterbook.org/en/stable/content/references.html#check-for-missing-references
 site:
-	jupyter-book build --all -W -n --keep-going .
+	jupyter-book build --html --ci --strict
+	# these point to the temporary server used for the build (http://localhost:3000), so let Read the Docs generate them instead
+	rm -f _build/html/robots.txt _build/html/sitemap.xml _build/html/sitemap_style.xsl
 
 # school can be columbia, nyu, or omitted for both
 preview:
@@ -62,8 +63,3 @@ build_dir := _build
 
 clean:
 	rm -rf $(build_dir)
-
-# https://github.com/jupyter-book/jupyter-book/issues/2271
-# https://stackoverflow.com/a/1583282/358804
-fix_double_escaping:
-	find $(build_dir)/html -name '*.html' -print0 | xargs -0 sed -i 's/&/\&/g'

_footer.md

@@ -0,0 +1 @@
+[![Creative Commons Zero 1.0](extras/img/cc-zero.svg)](https://creativecommons.org/publicdomain/zero/1.0/)

_static/styles.css

@@ -1,3 +1,5 @@
+/* included via site.options.style in myst.yml */
+
 iframe {
   width: 100%;
 }
@@ -16,33 +18,62 @@ article ol ol ol li {
 }
 
 /* keep outputs from being too long */
-.cell_output .output {
-  max-height: 20rem;
+[data-name="outputs-container"] {
+  max-height: 40rem;
   overflow-y: auto;
+}
 
-  /* for HTML outputs, go a bit longer, since this includes things like visualizations */
-  &.text_html {
-    max-height: 40rem;
-  }
+.course-term p {
+  font-size: 2rem;
+  font-weight: bold;
+  text-align: center;
+}
+
+/* show the "Open in Colab" link as a button in the page header, by overlapping it with the frontmatter block in the article grid. See extras/myst/colab.mjs. */
+article:has(> .colab-link) > .myst-fm-block {
+  grid-row: 1;
 }
+article > .colab-link {
+  grid-row: 1;
+  align-self: start;
+  justify-self: start;
+  z-index: 1;
+  /* line up with the header, below the frontmatter block's top padding (the theme resets margins) */
+  padding-top: 2.25rem;
 
-/* indicate the version by color, overriding the colors from sphinx-book-theme */
-/* top nav bar */
-.bd-header-article {
-  --pst-color-background: {{color}};
+  p {
+    margin: 0;
+  }
+  a {
+    display: block;
+    padding: 0 0.6rem;
+    border: 1px solid currentColor;
+    border-radius: 0.375rem;
+    font-size: 0.875rem;
+    /* match the header's height, including the border */
+    line-height: calc(1.5rem - 2px);
+    text-decoration: none;
+  }
+}
 
-  .btn {
-    --pst-color-text-base: white;
-    --pst-color-text-muted: white;
+.print-only {
+  display: none;
+}
+@media print {
+  .print-only {
+    display: block;
   }
+}
 
-  /* undo for dropdown menus */
-  .dropdown-menu {
-    --pst-color-background: white;
+/* indicate the version by color */
+.myst-top-nav {
+  background-color: {{color}};
+  color: white;
 
-    .btn {
-      --pst-color-text-base: #323232;
-      --pst-color-text-muted: #646464;
-    }
+  /* site title, menu button, and external links */
+  .myst-top-nav-bar > div:first-child a,
+  .myst-top-nav-bar > div:first-child button,
+  .myst-top-nav-bar > div:first-child + div a {
+    color: white;
   }
 }