refactor: migrate from Jupyter Book to MyST MD

.github/workflows/cd.yml

@@ -23,14 +23,14 @@ jobs:
 
       - uses: prefix-dev/setup-pixi@v0.9.6
         with:
-          pixi-version: v0.28.2
+          pixi-version: v0.69.0
 
       - name: Build the book
         run: pixi run book
 
       - uses: actions/upload-artifact@v7
         with:
-          name: jupyterbook
+          name: myst-site
           path: _build/html/*
 
   build-pyodide:
@@ -75,7 +75,7 @@ jobs:
 
       - uses: actions/download-artifact@v8
         with:
-          name: jupyterbook
+          name: myst-site
           path: public
 
       - uses: actions/download-artifact@v8

.gitignore

@@ -195,6 +195,10 @@ a.out
 compile_flags.txt
 Untitled*
 content/week*/06-rust/Cargo.lock
+content/week09_compiled/hello
+content/week09_compiled/mult
+content/week09_compiled/power
+content/week09_compiled/ramses/
 
 _output/Volumes
 *.doit.db

AGENTS.md

@@ -0,0 +1,52 @@
+# AGENTS.md
+
+MyST MD course site for *Software Engineering for Scientific Computing*.
+
+## Build & run
+
+| Target | Command |
+|--------|---------|
+| Book (with pixi) | `pixi run book` |
+| Pyodide / JupyterLite | `nox -s pyodide` |
+| Slides | `npx @marp-team/marp-cli@latest --input-dir slides --output _output` |
+| Live dev server (JupyterLab) | `pixi run lab` |
+
+- `pixi run book` installs a user-wide ipykernel (`conda-env-se-for-sci-py`) and builds the site using `myst build --execute --html`. It sets `PYDEVD_DISABLE_FILE_VALIDATION=1`.
+- `mystmd` is configured to **execute all notebooks** on every build (`--execute` flag).
+- Only files listed in the `toc` section of `myst.yml` are included in the build. The `notes/` directory is explicitly excluded and contains instructor notes—do not reference it as book content.
+
+## Environment
+
+- **Pixi** (`pixi.toml`) is the primary package manager. `environment.yml` duplicates the same Conda dependencies and should be kept in sync.
+- `pixi.lock` is checked in.
+- Nox sessions use `uv|virtualenv` by default (`nox.options.default_venv_backend`).
+
+## Content structure
+
+- `content/` — Book chapters (mix of `.md` and `.ipynb`).
+- `slides/` — Marp slide decks. These are rendered by CI and deployed to `public/slides`.
+- `notes/` — Instructor notes; not built into the book.
+- `myst.yml` drives the project configuration and table of contents.
+
+## Lint / format / pre-commit
+
+- Always use `prek -a --quiet` instead of `pre-commit run -a`.
+- Hooks include: ruff-format, blacken-docs, nbstripout, prettier, codespell, blocklint, plus a **custom `disallow-caps` hook** that rejects `PyBind`, `Numpy`, `Cmake`, `CCache`, `Github`, `PyTest`.
+- Prettier config (`.prettierrc.toml`): prose wraps at 80 chars by default, **but never for `slides/*.md`**.
+
+## CI / deploy
+
+`.github/workflows/cd.yml` builds three artifacts and deploys to GitHub Pages on push to `main`:
+1. Book via `pixi run book` (mystmd).
+2. Pyodide via `uvx nox -s pyodide`.
+3. Slides via `npx @marp-team/marp-cli@latest ...`.
+
+## Generated / ignored artifacts
+
+- Many `content/week*/` subdirs contain compiled examples (C++, Rust, Fortran). Build artifacts (`.so`, `.o`, `CMakeLists.txt`, `pyproject.toml`, etc.) inside those dirs are gitignored.
+- `_build/`, `_output/`, `.nox/`, `.pixi/`, `.ipynb_checkpoints` are ignored.
+
+## Nox bump helpers
+
+- `nox -s pc_bump` — bumps pre-commit versions embedded in course markdown (searches `content/**/*.md`).
+- `nox -s gha_bump` — bumps GitHub Actions versions embedded in course markdown.

content/week03_git/intro.md

@@ -21,7 +21,7 @@ Old school techniques are usually bad.
     complex
 
 - Disaster recover is a disaster.
-  - Oh F#@K! Did I just overwrite all my work from last night??!!!?
+  - Oh F#\@K! Did I just overwrite all my work from last night??!!!?
 
 ![title](phd101212s.png)
 

content/week10_binding/02-cpython/02-cpython.ipynb

@@ -207,7 +207,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "!python3 setup.py build_ext --inplace"
+    "!{sys.executable} setup.py build_ext --inplace"
    ]
   },
   {

content/week10_binding/03-pybind/03b-pybind.ipynb

@@ -169,7 +169,7 @@
    },
    "outputs": [],
    "source": [
-    "!cmake -GNinja -S . -B build\n",
+    "!cmake -GNinja -S . -B build -DCMAKE_POLICY_VERSION_MINIMUM=3.10\n",
     "!cmake --build build"
    ]
   },
@@ -537,7 +537,7 @@
    },
    "outputs": [],
    "source": [
-    "!{sys.executable} -m pip wheel . -v"
+    "!{sys.executable} -m pip wheel . -v -Ccmake.define.CMAKE_POLICY_VERSION_MINIMUM=3.10"
    ]
   },
   {

environment.yml

@@ -8,7 +8,7 @@ dependencies:
   - ipykernel >=6.0
   - ipython >=8.0
   - ipywidgets *
-  - jupyter-book *
+  - mystmd *
   - jupyterlab >=3
   - line_profiler *
   - matplotlib >=3.5
@@ -23,5 +23,4 @@ dependencies:
   - rich >=11
   - scikit-build-core >=0.8
   - scipy *
-  - sphinxcontrib-mermaid *
   - ninja >=1.10

myst.yml

@@ -0,0 +1,97 @@
+version: 1
+project:
+  title: Software Engineering For Scientific Computing
+  authors:
+    - name: Henry Schreiner
+    - name: Romain Teyssier
+  copyright: "Copyright 2022"
+  exclude:
+    - notes
+    - slides
+    - "**.*cache"
+    - "**.ipynb_checkpoints"
+    - "**.nox"
+    - "**.pixi"
+    - "**.virtual_documents"
+    - .DS_Store
+    - Thumbs.db
+    - "content/week10_binding/03-pybind/build"
+  settings:
+    output_stderr: remove-warn
+    output_matplotlib_strings: remove
+  toc:
+    - file: content/intro.md
+    - title: "Week 1: Intro"
+      children:
+        - file: content/week01_intro/intro.md
+        - file: content/week01_intro/setup.md
+        - file: content/week01_intro/vcs.md
+        - file: content/week01_intro/programming_basics.ipynb
+        - file: content/week01_intro/practices.md
+        - file: content/week01_intro/cleanup_bessel.ipynb
+        - file: content/week01_intro/python_setup.md
+    - title: "Week 2: Testing"
+      children:
+        - file: content/week02_testing/testing.md
+        - file: content/week02_testing/pytest.md
+        - file: content/week02_testing/tdd.md
+        - file: content/week02_testing/debugging.md
+    - title: "Week 3: Version Control"
+      children:
+        - file: content/week03_git/intro.md
+        - file: content/week03_git/first_steps.md
+        - file: content/week03_git/advanced_steps.md
+    - title: "Week 4: Packaging and Quality Control"
+      children:
+        - file: content/week04_package/packaging.md
+        - file: content/week04_package/using_packages.md
+        - file: content/week04_package/making_a_package.md
+        - file: content/week04_package/precommit.md
+        - file: content/week04_package/task_runners.md
+    - title: "Week 5: Continuous Integration"
+      children:
+        - file: content/week05_ci/ci.md
+        - file: content/week05_ci/cd.md
+        - file: content/week05_ci/docs.md
+    - title: "Week 6: Object Oriented design"
+      children:
+        - file: content/week06_oop/introoo.md
+        - file: content/week06_oop/oodesign.md
+    - title: "Week 7: Design Patterns"
+      children:
+        - file: content/week07_design/designpatt.md
+        - file: content/week07_design/functional.md
+    - title: "Week 8: Static Typing & Profiling"
+      children:
+        - file: content/week08_static_typing/typing.md
+    - title: "Week 9: Intro to Compilation"
+      children:
+        - file: content/week09_compiled/Compiled_Languages.ipynb
+        - file: content/week09_compiled/rust_example/compiled.md
+        - file: content/week09_compiled/rust_example/rust.md
+        - file: content/week09_compiled/debugging.md
+        - file: content/week09_compiled/profiling.md
+    - title: "Week 10: Mixing Languages"
+      children:
+        - file: content/week10_binding/01-shared-objects/01-shared-objects.ipynb
+        - file: content/week10_binding/02-cpython/02-cpython.ipynb
+        - file: content/week10_binding/03-pybind/03a-pybind.ipynb
+        - file: content/week10_binding/03-pybind/03b-pybind.ipynb
+        - file: content/week10_binding/06-rust.md
+    - title: "Week 11: Parallel Computing"
+      children:
+        - file: content/week11_omp/intro.md
+        - file: content/week11_omp/openmp.md
+        - file: content/week11_omp/threading.md
+        - file: content/week11_omp/concepts.md
+    - title: "Week 12: GPUs"
+      children:
+        - file: content/week12_mpi/mpi.md
+    - title: "Bonus: Exotic topics"
+      children:
+        - file: content/week13_misc/webassembly.md
+        - file: content/week13_misc/shell.md
+site:
+  actions:
+    - title: Source Repository
+      url: https://github.com/se-for-sci/se-for-sci.github.io