feat: update to jupyter book 2

.github/workflows/docs.yml

@@ -1,58 +1,47 @@
-name: Build and publish docs
+# This file was created automatically with `myst init --gh-pages` 🪄 💚
 
+name: MyST GitHub Pages Deploy
 on:
   push:
     branches:
       - main
       - ci/test*
-
+env:
+  # `BASE_URL` determines the website is served from, including CSS & JS assets
+  # You may need to change this to `BASE_URL: ''`
+  BASE_URL: /${{ github.event.repository.name }}
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
 jobs:
-  docs:
-    name: Build Jupyter Book and publish to GitHub Pages
-    runs-on: ubuntu-latest
-
-    # This job is responsible for the GH Pages deployment
+  deploy:
     environment:
       name: github-pages
-      url: ${{ steps.gh_pages_deployment.outputs.page_url }}
-
-    # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
-    permissions:
-      contents: read
-      pages: write
-      id-token: write
-
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v3
-
-      - name: Set up Python
-        run: uv python install
-
-      # Required to execute notebooks with Python modules wrapping Node.js modules, such as Draco 1
-      - name: Setup Node
-        uses: actions/setup-node@v4
-
-      # Installing system dependencies required by notebooks to be executed
-      - name: Install system dependencies
-        run: sudo apt-get update && sudo apt-get install -y gringo
-
-      - name: Make book
-        run: make book
-
-      - name: Display HTML bundle tree
-        run: find docs/_build/html/ | sed -e "s/[^-][^\/]*\// |/g" -e "s/|\([^ ]\)/|-\1/"
-
       - name: Setup Pages
-        uses: actions/configure-pages@v5
-
-      - name: Upload Documentation Site Artifact
+        uses: actions/configure-pages@v3
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18.x
+      - name: Install MyST Markdown
+        run: npm install -g mystmd
+      - name: Build HTML Assets
+        run: cd docs && myst build --html
+      - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: ./docs/_build/html
-
+          path: "./docs/_build/html"
       - name: Deploy to GitHub Pages
-        id: gh_pages_deployment
+        id: deployment
         uses: actions/deploy-pages@v4

.gitignore

@@ -68,8 +68,9 @@ instance/
 # Scrapy stuff:
 .scrapy
 
-# Sphinx documentation
+# Documentation
 docs/_build/
+docs/exports/
 
 # PyBuilder
 target/

Makefile

@@ -1,6 +1,6 @@
 PACKAGE_ROOT = draco
 
-all: lint typecheck cover book grounding-size
+all: lint typecheck cover book-html book-pdf grounding-size
 
 .PHONY: install
 install:
@@ -40,27 +40,25 @@ mypy:
 pytype:
 	@uv run --all-extras pytype $(PACKAGE_ROOT)
 
-.PHONY: jupyterlite-nb-patch
-jupyterlite-nb-patch:
-	@uv run --with nbformat python docs/jupyterlite_nb_patch.py
-
 book:
+	@echo "==> 📕 Start Book"
+	@cd docs && uv run --all-extras jupyter-book start
+
+book-html:
 	@echo "==> 📕 Book"
-	@uv run --all-extras jupyter-book build docs
-	@make jupyterlite-nb-patch
+	@cd docs && uv run --all-extras jupyter-book build
+
+book-pdf:
+	@echo "==> 📕 Start Book"
+	@cd docs && uv run --all-extras jupyter-book build --pdf
 
 # This command does NOT support hot-reloading,
 # but it is useful to quickly get a preview of how the deployed docs would look like.
 # Especially useful for previewing `{eval-rst}` blocks.
 .PHONY: book-serve
-book-serve: book
-	@echo "==> 📡 Serving Book at http://localhost:5000"
-	@uv run python -m http.server --directory docs/_build/html --bind 0.0.0.0 5000
-
-.PHONY: book-strict
-book-strict:
-	@uv run --all-extras jupyter-book build -W -n --keep-going docs
-	@make jupyterlite-nb-patch
+book-serve: book-html
+	@echo "==> 📡 Serving Book at http://localhost:5001"
+	@uv run python -m http.server --directory docs/_build/site/public --bind 0.0.0.0 5001
 
 .PHONY: lab
 lab:

docs/myst.yml

@@ -0,0 +1,60 @@
+version: 1
+project:
+  title: Draco
+  authors:
+    - name: CMU Data Interaction Group
+  copyright: 2023-2024
+  github: cmudig/draco2
+  thebe:
+    binder:
+      repo: cmudig/draco2
+      provider: github
+      url: https://mybinder.org
+      ref: main
+  bibliography:
+    - references.bib
+  exports:
+    - format: pdf
+      template: plain_latex_book
+      output: exports/book.pdf
+  # To autogenerate a Table of Contents, run "jupyter book init --write-toc"
+  toc:
+    - file: intro.md
+    - title: Facts
+      children:
+        - file: facts/intro.md
+        - file: facts/schema.md
+        - file: facts/view.md
+        - file: facts/mark.md
+        - file: facts/encoding.md
+        - file: facts/scale.md
+        - file: facts/task.md
+        - file: facts/facet.md
+        - file: facts/examples.ipynb
+    - title: API
+      children:
+        - file: api/intro.md
+        - file: api/draco.ipynb
+        - file: api/schema.ipynb
+        - file: api/run.ipynb
+        - file: api/facts.ipynb
+        - file: api/programs.md
+        - file: api/debug.md
+        - file: api/renderer.md
+        - file: api/server.md
+    - title: Applications
+      children:
+        - file: applications/recommendation.ipynb
+        - file: applications/draco_learn.ipynb
+        - file: applications/debug_draco.ipynb
+        - file: applications/server.md
+        - file: applications/renderer.ipynb
+        - file: applications/design_space_exploration.ipynb
+        - file: applications/draco1_vs_draco2.ipynb
+    - title: Reference
+      children:
+        - file: bibliography.md
+site:
+  options:
+    favicon: favicon.ico
+  template: book-theme

pyproject.toml

@@ -51,7 +51,7 @@ docs = [
     "clyngor>=0.4.3",
     "draco1",
     "ipywidgets>=8.1.5",
-    "jupyter-book>=1.0.3",
+    "jupyter-book>=v2.0.0a0",
     "jupyterlab>=4.3.0",
     "jupyterlite-pyodide-kernel>=0.4.3",
     "jupyterlite-sphinx>=0.16.5",