Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 35 additions & 19 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,52 +1,68 @@
# AGENTS.md

MyST MD course site for *Software Engineering for Scientific Computing*.
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.
| 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** (`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`).
- 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`.
- `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`**.
- 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`:
`.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.
- 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 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.
2 changes: 1 addition & 1 deletion content/week01_intro/intro.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Introductions and motivation

[Slides](https://se-for-sci.github.io/slides/week-01-1)
{button}`Slides <https://se-for-sci.github.io/slides/week-01-1>`

## The importance of software engineering in scientific computing

Expand Down
2 changes: 2 additions & 0 deletions content/week01_intro/vcs.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Version control overview

{button}`Slides <https://se-for-sci.github.io/slides/week-01-2>`

Our course material is in Git. All the open-source software we use is in Git.
Linux is in Git. It's the basis of modern software development. We'll work on
Git in detail later, but here are a few quick basics:
Expand Down
2 changes: 1 addition & 1 deletion content/week02_testing/testing.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Intro to testing

[Slides](https://se-for-sci.github.io/slides/week-03-1)
{button}`Slides <https://se-for-sci.github.io/slides/week-03-1>`

## Why Test?

Expand Down
2 changes: 1 addition & 1 deletion content/week04_package/packaging.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Packaging and quality control

[Slides](https://se-for-sci.github.io/slides/week-05-1)
{button}`Slides <https://se-for-sci.github.io/slides/week-05-1>`

Now you have your Git Repo, it's time to talk about how you structure it to make
it distributable and usable by others. We'll focus on building a Python package,
Expand Down
2 changes: 1 addition & 1 deletion content/week06_oop/introoo.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ kernelspec:

# Intro to Object Oriented Programming (OOP)

[Slides](https://se-for-sci.github.io/slides/week-06-1)
{button}`Slides <https://se-for-sci.github.io/slides/week-06-1>`

## Objects as collections of data and functions

Expand Down
2 changes: 1 addition & 1 deletion content/week06_oop/oodesign.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ kernelspec:

# Object Oriented Design

[Slides](https://se-for-sci.github.io/slides/week-06-2)
{button}`Slides <https://se-for-sci.github.io/slides/week-06-2>`

## Intro

Expand Down
2 changes: 1 addition & 1 deletion content/week07_design/designpatt.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ print = console.print

# Design patterns

[Slides](https://se-for-sci.github.io/slides/week-07-2)
{button}`Slides <https://se-for-sci.github.io/slides/week-07-2>`

Let's move beyond OO and learn from other paradigms and patterns. These are not
exclusive - you may use some or all of the ideas here to inform your class
Expand Down
2 changes: 1 addition & 1 deletion content/week07_design/functional.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ kernelspec:

# Functional programming

[Slides](https://se-for-sci.github.io/slides/week-07-1)
{button}`Slides <https://se-for-sci.github.io/slides/week-07-1>`

## Mutability and state

Expand Down
2 changes: 1 addition & 1 deletion content/week08_static_typing/typing.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Static Typing

[Slides](https://se-for-sci.github.io/slides/week-08-1)
{button}`Slides <https://se-for-sci.github.io/slides/week-08-1>`

What is the best thing about Python? One of the first things you'll hear: no
explicit typing.
Expand Down
Loading