Migrate course site pipeline to Jupyter Book 2 with MyST config

.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

@@ -20,7 +20,9 @@
     # https://github.com/gjtorikian/html-proofer/issues/663#issuecomment-989274727
     /(?<=\.pdf)#.*$/ => "",
     # make absolute links relative
-    %r{^https://python-public-policy\.afeld\.me/en/\w+} => ""
+    %r{^https://python-public-policy\.afeld\.me/en/\w+} => "",
+    # Jupyter Book 2 builds pages as /<path>/index.html by default
+    %r{^/(.+)\.html(#.*)?$} => '/\1/\2'
   }
 }
 HTMLProofer.check_directory("_build/html", options).run

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

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
 

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

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",