Migrate to Jupyter Book 2

.github/workflows/publish.yml

@@ -18,15 +18,6 @@ jobs:
       - name: Checkout the branch
         uses: actions/checkout@v3
 
-      - name: Jupyter Book cache
-        id: cache
-        uses: actions/cache@v3
-        with:
-          path: ./jupyter_cache
-          key: jupyter-cache-${{ github.run_id }}
-          restore-keys: |
-            jupyter-cache
-
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
@@ -37,9 +28,10 @@ jobs:
           pip install -r requirements.txt
 
       - name: Build the book
+        env:
+          BASE_URL: /${{ github.event.repository.name }}
         run: |
-          mkdir -p ./jupyter_cache
-          jupyter-book build -nv --keep-going book
+          cd book && jupyter book build --execute --html
 
       - name: Publish to GitHub Pages
         uses: JamesIves/github-pages-deploy-action@v4

.github/workflows/test.yml

@@ -12,15 +12,6 @@ jobs:
       - name: Checkout the branch
         uses: actions/checkout@v3
 
-      - name: Jupyter Book cache
-        id: cache
-        uses: actions/cache@v3
-        with:
-          path: ./jupyter_cache
-          key: ${{ github.event.number }}-jupyter-cache-${{ github.run_id }}
-          restore-keys: |
-            ${{ github.event.number }}-jupyter-cache
-
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
@@ -29,9 +20,7 @@ jobs:
       - name: Install dependencies
         run: |
           pip install -r requirements.txt
+
       - name: Build the book
         run: |
-          mkdir -p ./jupyter_cache
-          ls ./jupyter_cache
-          jupyter-book build -n --keep-going book
-          ls ./jupyter_cache
+          cd book && jupyter book build --execute --html

.gitignore

@@ -5,3 +5,4 @@ _build
 *_version.py
 /jupyter_cache/
 .DS_Store
+*.bak

README.md

@@ -1,3 +1,60 @@
-# The sampling book
+# The Sampling Book
 
-The sampling book is a series of tutorials on sampling algorithms built with the [Blackjax](https://github.com/blackjax-devs/blackjax) library.
+The Sampling Book is a series of tutorials on sampling algorithms built with the [BlackJAX](https://github.com/blackjax-devs/blackjax) library. The book is built with [Jupyter Book 2](https://jupyterbook.org/) and published to GitHub Pages.
+
+## Setup
+
+Install dependencies into a conda/mamba environment:
+
+```bash
+mamba create -n sampling_book python=3.13
+mamba activate sampling_book
+pip install -r requirements.txt
+```
+
+## Building the book
+
+Build the static site with notebook execution:
+
+```bash
+cd book && jupyter book build --execute --html
+```
+
+Static HTML output goes to `book/_build/html/`.
+
+For a local preview with live reload:
+
+```bash
+cd book && jupyter book start --execute
+```
+
+This serves the book at `http://localhost:3000`.
+
+## Contributing
+
+All tutorial notebooks are MyST Markdown files (`.md`) under `book/`, organized into:
+
+- `book/algorithms/` — sampling algorithm showcases
+- `book/models/` — model-specific examples
+
+### Converting between `.ipynb` and `.md`
+
+Notebooks are stored as MyST Markdown (`.md`) via [jupytext](https://jupytext.readthedocs.io/). To convert between formats during development:
+
+```bash
+# .md → .ipynb (for interactive editing in Jupyter)
+jupytext --to ipynb book/algorithms/my_notebook.md
+
+# .ipynb → .md (convert back before committing)
+jupytext --to myst book/algorithms/my_notebook.ipynb
+```
+
+Only commit the `.md` files — `.ipynb` files are for local development only.
+
+### Linting
+
+Pre-commit hooks enforce formatting (black, isort, flake8) for both Python source and notebooks:
+
+```bash
+pre-commit run --all-files
+```

book/models/hierarchical_bnn.md

@@ -14,7 +14,7 @@ kernelspec:
 # Hierarchical Bayesian Neural Networks
 
 Code is based on  [This blog post](https://twiecki.io/blog/2018/08/13/hierarchical_bayesian_neural_network/) by [Thomas Wiecki](https://twitter.com/twiecki) (see
-[Original PyMC3 Notebook](https://github.com/twiecki/WhileMyMCMCGentlySamples/blob/master/content/downloads/notebooks/bayesian_neural_network_hierarchical.ipynb)). Converted to Blackjax by Aleyna Kara (@karalleyna) and Kevin Murphy (@murphyk). (For a Numpyro version, see [here](https://github.com/probml/probml-notebooks/blob/main/notebooks/bnn_hierarchical_numpyro.ipynb).)
+[Original PyMC3 Notebook](https://github.com/twiecki/WhileMyMCMCGentlySamples/blob/master/content/downloads/notebooks/bayesian_neural_network_hierarchical.ipynb)). Converted to Blackjax by Aleyna Kara ([@karalleyna](https://github.com/karalleyna)) and Kevin Murphy ([@murphyk](https://github.com/murphyk)). (For a Numpyro version, see [here](https://github.com/probml/probml-notebooks/blob/main/notebooks/bnn_hierarchical_numpyro.ipynb).)
 
 We create T=18 different versions of the "two moons" dataset, each rotated by a different amount. These correspond to T different nonlinear binary classification "tasks" that we have to solve. We only get a few labeled samples from each each task, so solving them separately (with T independent MLPs, or multi layer perceptrons) will result in poor performance. If we pool all the data, and fit a single MLP, we also get poor performance, because we are mixing together different decision boundaries. But if we use a hierarchical Bayesian model, with one MLP per task, and one learned prior MLP,  we will get better results, as we will see.
 

book/models/mlp.md

@@ -433,7 +433,7 @@ ax.set_ylabel("# uncertain predictions");
 Perhaps unsurprisingly, the digit 8 is overrepresented in the set of examples $i$ for which $\max_d P(y_i=d|x_i) < 0.95$. As a purely academic exercise and sanity test of sort, let us now re-compute the point-wise accuracy ignoring the digits for which the model is uncertain, varying the threshold above which we consider the model to be certain:
 
 ```{code-cell} ipython3
-:args: [hide-cell]
+:tags: [hide-cell]
 
 def compute_accuracy(probs, y):
     predicted = jnp.argmax(probs, axis=1)
@@ -443,7 +443,7 @@ def compute_accuracy(probs, y):
 ```
 
 ```{code-cell} ipython3
-:args: [hide-cell]
+:tags: [hide-cell]
 
 thresholds = np.linspace(0.1, 1.0, 90)
 
@@ -458,7 +458,7 @@ for t in thresholds:
 ```
 
 ```{code-cell} ipython3
-:args: [hide-input]
+:tags: [hide-input]
 
 _, axes = plt.subplots(1, 2, figsize=(10, 4))
 axes[0].plot(thresholds, accuracies)

book/myst.yml

@@ -0,0 +1,50 @@
+version: 1
+project:
+  title: The Sampling Book Project
+  authors:
+    - name: The Blackjax Team
+  exclude:
+    - README.md
+  github: blackjax-devs/sampling-book
+  bibliography:
+    - references.bib
+  exports:
+    - format: pdf
+      template: plain_latex_book
+      output: exports/book.pdf
+  toc:
+    - file: index.md
+    - title: Algorithms
+      children:
+        - file: algorithms/contour_sgld.md
+        - file: algorithms/cyclical_sgld.md
+        - file: algorithms/pathfinder.md
+        - file: algorithms/PeriodicOrbitalMCMC.md
+        - file: algorithms/TemperedSMC.md
+        - file: algorithms/TemperedSMCWithOptimizedInnerKernel.md
+        - file: algorithms/SMCvsPersistentSampling.md
+        - file: algorithms/mclmc.md
+        - file: algorithms/meads.md
+        - file: algorithms/laps.md
+        - file: algorithms/low_rank_mass_matrix.md
+    - title: Models
+      children:
+        - file: models/change_of_variable_hmc.md
+        - file: models/GP_EllipticalSliceSampler.md
+        - file: models/GP_Marginal.md
+        - file: models/sparse_regression.md
+        - file: models/logistic_regression.md
+        - file: models/LogisticRegressionWithLatentGaussianSampler.md
+        - file: models/mlp.md
+        - file: models/hierarchical_bnn.md
+        - file: models/RegimeSwitchingModel.md
+        - file: models/probabilistic_ode_solver_parameter_estimation.md
+site:
+  title: The Sampling Book
+  actions:
+    - title: GitHub
+      url: https://github.com/blackjax-devs/sampling-book
+  options:
+    logo: blackjax.png
+    folders: true
+  template: book-theme

requirements.txt

@@ -5,7 +5,7 @@
 # Build the book
 ipython
 jupyter-cache
-jupyter-book<2.0
+jupyter-book>=2
 jupytext
 
 # Dependencies for the notebooks