Migrate to Jupyter Book 2

.readthedocs.yaml

@@ -7,16 +7,12 @@ python:
       command: sync
 
 build:
-  os: ubuntu-lts-latest
+  os: ubuntu-22.04
   tools:
-    python: "3"
-  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
+    python: "3.12"
+    nodejs: "22"
+  commands:
+    - jupyter-book build --html
+    - mkdir -p $READTHEDOCS_OUTPUT/html/
+    - cp -r _build/html/. "$READTHEDOCS_OUTPUT/html"
+    - make fix_double_escaping build_dir="$READTHEDOCS_OUTPUT"

Makefile

@@ -23,7 +23,7 @@ format:
 
 # 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 --all --ci
 
 setup:
 	uv sync

extras/scripts/broken_links.rb

@@ -19,6 +19,9 @@
     # ignore PDF page hash
     # https://github.com/gjtorikian/html-proofer/issues/663#issuecomment-989274727
     /(?<=\.pdf)#.*$/ => "",
+    # Redirect files generated from old JB1 .html URLs don't contain anchors.
+    # Strip hashes so linkcheck validates file existence without false anchor failures.
+    /(?<=\.html)#.*$/ => "",
     # make absolute links relative
     %r{^https://python-public-policy\.afeld\.me/en/\w+} => ""
   }

extras/scripts/school_ci.sh

@@ -14,7 +14,7 @@ git rm -r \
     extras/terraform/ \
     extras/**/test_*.py
 
-# match the conditionals in _toc.yml
+# match the conditionals in myst.yml
 if [ "$SCHOOL" = "columbia" ]; then
     git rm -r meta/adrs*
 else
@@ -26,4 +26,11 @@ fi
 
 make site
 
+# Generate redirects from old Jupyter Book 1 URLs to Jupyter Book 2 URLs.
+uv run --with click --with pyyaml \
+    https://raw.githubusercontent.com/jupyter-book/jb1-redirect-generator/main/generate_redirects.py \
+    --base-url "https://python-public-policy.afeld.me/en/$SCHOOL/" \
+    --output-dir _build/html \
+    --myst-config myst.yml
+
 git diff

meta/instructor_guide.md

@@ -23,7 +23,7 @@ make slides lec=N
 
 ## Site
 
-The site is generated using [JupyterBook](https://jupyterbook.org/) and deployed to [ReadTheDocs](https://readthedocs.org/). Markdown (`.md`) files and the files and folders that start with an underscore (`_`) are related to JupyterBook.
+The site is generated using [JupyterBook](https://jupyterbook.org/) and deployed to [ReadTheDocs](https://readthedocs.org/). Markdown (`.md`) files, [`myst.yml`](../myst.yml), and files and folders that start with an underscore (`_`) are related to JupyterBook.
 
 ### Publishing
 
@@ -41,6 +41,7 @@ For each school, [the workflow](../.github/actions/setup/action.yml):
    - It uses {% raw %}`{% if id == "columbia" %}` and `{% if id == "nyu" %}`{% endraw %} conditionals for school-only content; the generated files must contain neither Jinja tags nor identifiers for the other school.
    - For notebooks, `school.sh` first removes cells tagged for the other school (`columbia-only` or `nyu-only`) and cells tagged `remove`. It then renders each remaining cell source with the same Jinja variables, while resetting notebook kernel metadata to the default Python kernel for Colab.
 1. Runs `make site`, which builds the Jupyter Book HTML into `_build/html`.
+1. Generates redirects from old Jupyter Book 1 `.html` paths to Jupyter Book 2 URLs using [jb1-redirect-generator](https://github.com/jupyter-book/jb1-redirect-generator).
 1. When the push is to `main`, the workflow pushes the amended commit to the relevant school branch. Pushes to other branches still render both versions and upload their HTML, but do not update either published branch.
 1. ReadTheDocs is notified of updates to the school-specific branches, which are then built as separate [versions](https://docs.readthedocs.com/platform/stable/versions.html).
 

myst.yml

@@ -0,0 +1,110 @@
+version: 1
+project:
+  id: f6e67d86-5ff0-4f42-ab5a-a421c82f8f9e
+  title: "{{course_name}} @ {{school_name}}"
+  authors:
+    - name: Aidan Feldman
+  exclude:
+    - .github/*
+    - .pytest_cache/*
+    - tmp/*
+  github: afeld/python-public-policy
+  toc:
+    - file: home.md
+    - file: index.md
+      title: Homepage
+    - file: syllabus.md
+      children:
+        - file: registration.md
+        - file: joining_late.md
+        - file: exam.md
+        {% if id == "columbia" -%}
+        - file: curve.ipynb
+        {%- endif %}
+    - file: resources.md
+      children:
+        - file: brackets.ipynb
+          title: Brackets
+    - url: "{{lms_url}}"
+      title: "{{lms_name}}"
+    - url: "{{discussions_url}}"
+      title: Ed Discussion
+    - url: https://colab.research.google.com
+      title: Google Colab
+    - url: "{{submission_tool_url}}"
+      title: Gradescope
+    - file: lectures.md
+      children:
+        - file: lecture_0.ipynb
+        - file: lecture_1.ipynb
+          children:
+            - file: lecture_1_exercise.ipynb
+              title: In-class exercise
+            - file: lecture_1_exercise_solution.ipynb
+              title: In-class exercise solution
+            - file: lecture_1_demo_solution.ipynb
+              title: Demo solution
+        - file: lecture_2.ipynb
+          children:
+            - file: lecture_2_exercise.ipynb
+              title: In-class exercise
+            {% if id == "columbia" -%}
+            - file: lecture_2_exercise_2_solution.ipynb
+              title: Exercise 2 solution
+            {%- endif %}
+        - file: lecture_3.ipynb
+          children:
+            - file: lecture_3_exercise_solution.ipynb
+              title: In-class exercise solution
+            - file: lecture_3_demo_solution.ipynb
+              title: Demo solution
+        - file: lecture_4.ipynb
+          children:
+            - file: lecture_4_demo_solution.ipynb
+              title: Demo solution
+        - file: lecture_5.ipynb
+          children:
+            - file: lecture_5_exercise_solution.ipynb
+              title: In-class exercise solution
+        - file: lecture_6.ipynb
+    - file: assignments.md
+      title: Assignments
+      children:
+        - file: assignments/open_ended.md
+        - file: hw_0.ipynb
+        - file: hw_1.md
+        - file: hw_2.ipynb
+        - file: hw_3.ipynb
+        - file: hw_4.md
+        - file: final_project.md
+          children:
+            - file: final_project/proposal.md
+              title: Proposal
+            - file: final_project/resources.md
+              title: Resources
+            - file: final_project/peer_grading.md
+              title: Peer grading
+            - file: final_project/examples.md
+              title: Examples
+              children:
+                - file: final_project/creepy_crawly.ipynb
+                - file: final_project/lead.ipynb
+                - file: final_project/universities.ipynb
+    - file: meta.md
+      children:
+        - file: meta/assistant_guide.md
+          children:
+            - file: meta/ed_helper.ipynb
+        - file: meta/instructor_guide.md
+        {% if id == "nyu" -%}
+        - file: meta/adrs.md
+          children:
+            - file: meta/adrs/plotting.md
+              title: Plotting
+            - file: meta/adrs/submission.md
+              title: Submission
+        {%- endif %}
+site:
+  template: book-theme
+  options:
+    folders: true

pyproject.toml

@@ -35,10 +35,11 @@ dependencies = [
     # https://plotly.com/python/getting-started/#jupyterlab-support
     "anywidget",
     "isoduration",
-    "jupyter-book==1.*",
+    "jupyter-book==2.*",
 
     # CI
     "jinja2",
+    "markdown-it-py",
     "nbconvert[webpdf]>=7.16.6",
     "nbdime",
     "pytest",