From c5b766bcd454768a060c1cba404d7d8319dfe130 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Wed, 1 Jul 2026 13:59:10 -0400 Subject: [PATCH 1/3] chore: add an AGENTS file Assisted-by: ClaudeCode:claude-opus-4.8 Signed-off-by: Henry Schreiner --- .github/CONTRIBUTING.md | 16 ++++++++++++---- .gitignore | 4 ++++ AGENTS.md | 29 +++++++++++++++++++++++++++++ 3 files changed, 45 insertions(+), 4 deletions(-) create mode 100644 AGENTS.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index de5c127..d00b30b 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -6,13 +6,19 @@ Contributions are welcome! This project is a workshop book built with [MyST](htt ### Prerequisites -- [Node.js](https://nodejs.org/) (for building the book and slides) +- [bun](https://bun.sh/) (for building the book and slides) - [prek](https://github.com/j178/prek) (for linting) +Install dependencies with: + +```bash +bun install +``` + ## Building the book ```bash -npx mystmd build --html +bun run build-book ``` The output is placed in `_build/html/`. @@ -20,10 +26,12 @@ The output is placed in `_build/html/`. ## Building the slides ```bash -npx @marp-team/marp-cli@latest --input-dir slides --output _output +bun run build-slides ``` -The output is placed in `_output/`. +The output is placed in `_build/html/slides/`. + +To build both at once, run `bun run build`. ## Linting diff --git a/.gitignore b/.gitignore index c205114..1ee830a 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,7 @@ _build _output node_modules .DS_Store + +# Symlink to AGENTS.md +CLAUDE.md +.claude/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..c770750 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,29 @@ +# Agent instructions + +## What this is + +SIMPLE-Py is a workshop that teaches simple compiled Python packaging (C++, Rust, publishing). It is **content, not code**: a [MyST](https://mystmd.org/) book plus [Marp](https://marp.app/) slides, deployed to GitHub Pages. There is no Python package to build or test here — edits are to Markdown. + +## Commands + +Package manager is **bun** (see `bun.lock`; CI runs `bun install --frozen-lockfile`). + +```bash +bun run serve # live-preview the book (myst start) +bun run build # build book + slides into _build/html/ (build-book then build-slides) +bun run build-book # myst build --html +bun run build-slides # marp slides/ -> _build/html/slides/ +bun run clean # rm -rf _build +prek -a --quiet # lint/format everything (ruff-format, blacken-docs, prettier, codespell, etc.) +``` + +## Structure + +- **`content/`** — book chapters as Markdown, grouped by section directory (`basic-packaging/`, `compiled/`, `scikit-build/`, `other-tools/`, `interesting/`). Files are prefixed with an order number (`01_`, `02_`, …). Images live alongside their chapter, prefixed with the chapter stem (e.g. `04_distros-shipping.jpg`). +- **`myst.yml`** — book config and the **table of contents**. Adding or reordering a chapter file requires editing the `toc` here; the filesystem order is not authoritative. +- **`slides/`** — Marp decks (`marp: true` frontmatter, `theme: simplepy` → `slides/simplepy.css`). Named `
__.md` where the leading digit ties the deck to its content section. + +## Conventions + +- `blacken-docs` formats Python code blocks inside Markdown, and `ruff-format` runs on code — keep embedded code snippets valid and formatted. +- CI (`.github/workflows/cd.yml`) builds with `BASE_URL: /SIMPLE-Py` and deploys to Pages on push to `main`. From 766b6d657be6e6470394774a66c37dec46414114 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Wed, 1 Jul 2026 14:10:26 -0400 Subject: [PATCH 2/3] fix: vendor favicon to avoid flaky mystmd.org fetch in CI The book build fetched the default favicon from https://mystmd.org/favicon.ico on every run, which intermittently failed with ERR_STREAM_PREMATURE_CLOSE and broke the build job. Ship the favicon locally and point myst.yml at it so the build has no network dependency for it. Assisted-by: ClaudeCode:claude-opus-4.8 --- favicon.ico | Bin 0 -> 41662 bytes myst.yml | 4 +++- 2 files changed, 3 insertions(+), 1 deletion(-) create mode 100644 favicon.ico diff --git a/favicon.ico b/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..2d6ab2c5bdf0143291cd7da5c9bb2c2d3fdb0683 GIT binary patch literal 41662 zcmeHOL2m0d5S5WdmdUEOTgSKZ|Z_VVv?1o;LD z(2WZiR^O8)e~RYNlp=l0_V{B$4LKanyf>ui1V4&K`1kc|gr9Nr&)-q>QxrwNL(mm{ zgRq~U`eihv@Z2q*%IfFhs>C<2OrBA^H;0*Zhlpa|R?0>Az7Zvx3( za&uq|AYt$@adA=hJq{qmn+gHAryf3%n*w71$%2bF4<9cB2=Qh@01x83qvYrvt)5vw zpdyGf#J4x9cl_c9gmcqNG~lA*M9-}rDyHONik9b4g>`7V#GIsuurAgm@n|74%;6o1 zc!px{v&-OTQTpUvxp7RFNC5JTA;j_((x#q$m`Y>BS{m!RpKCFY={fu1C$pve0=F1V|Ji8WcS_vo$^&<51=UC#iNj`}-Ky zaP7n8P%s!;9Keg`hF!m%;syT`$ii4B85#~li3b=}dxX5aKzh6D!1p6$I+Wap7zgm- z{U;e>Y#Ngypa>`eihv@Z2q*%IKz9gy`SK-&YxK0IZy_gAe zLb#xf*S8Srpt_L*>o|eTAPb0H)6A27FOcHQK^vb+0yY_hb8T4!%w;^)S@-JjL7()` zc&3o#l+Q~YM{Y}qjiL8!vU4Rq4j-n^Mt_qLe5Llf*Qg`+F8GjYy5gh}mdZ!_{Q>M^ z0l$h1wpo)}7W_5hw8?ryvPJHn+8>zD_l$|X^gId8TkxlRoB$BGx$d|UAHnY=<>RQn zgRlc`yra4B&xHQ?1jWU$FgFdEd+9dFed)+Qln)o~@9_8J@JZf+{y(QMSNZT18!+Sd z1!8PVfgAdljxlm|^6u-H$2F7>KOZi#D!?zjsR7uaz>*nG78otE-pf@?ej*fOoD#1cX~Tb#es za@cWRT621(3i4b!@;}-iu#w))ucx5#%spC%z8vu=9~Q{KXd&Q~Sf)tB*oVC| z244%oUsBBx#?xy2np@=V!n?>FV^0D$&UrLrhl>khb$I8t<)NAfU$KDu zQs}>BK8U?bo+>=MXt9Qby=!gdqt3~)3l2;l;A1NAu6)$7ci}NLvFz#@d}M)~q+P8! zG(X5cfv`4Hi0htX^YQ6Bu7p7ugT0`eihv@Z2q*%IfFhs>Tpj|s@%cdbhMHfjzPl^ZIK;mj zHPg3y7!LC{mi`gV>F_YVipGY%Dyrb28sC&fF)!`cr9Lk86nYG~FLgXdGsxXu-%&@;g4~?HuO1T%Qw+;F}~holjqTRuOranv)b#cajCCM{khaX z9t!)_ywo?PUaI+audfgKe*S+4Jul{0D%zfO7V!pfR{o*i*Y%yP-(|DOU?e{NS|Bdb$uN_*T!vqHLH)WX5*TD`eEsthx)jskGA#k(e~c7 z|Mkw+cX#IaFZZ^dkLu%f{pW`xJvHqg$GNSq5(EF}IX|VZBh!A4{ZQAz$ajA6Z0p62 oFZo~L^w=2nfSp*cFX&sd-mt@LeP@hg<^89p`mfwq_1mldKTd~`6aWAK literal 0 HcmV?d00001 diff --git a/myst.yml b/myst.yml index e8c4dd2..5bc16b4 100644 --- a/myst.yml +++ b/myst.yml @@ -46,5 +46,7 @@ site: template: book-theme options: logo_text: SIMPLE-Py - # favicon: favicon.ico + # Vendored so the build never fetches mystmd.org's default favicon, which + # fails intermittently in CI (ERR_STREAM_PREMATURE_CLOSE). + favicon: favicon.ico # logo: site_logo.png From 130b5e5a00c550247f8f88ece37da4be1c87a541 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Wed, 1 Jul 2026 14:14:54 -0400 Subject: [PATCH 3/3] fix: copy content images into the book build marp/myst don't emit images that live alongside content chapters, so slides and pages referencing them 404 on the deployed site. rsync the image files from content/ into _build/html/content/ after the slide build. Assisted-by: ClaudeCode:claude-opus-4.8 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index e5fef1a..85e146a 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "type": "module", "scripts": { "build-book": "myst build --html", - "build-slides": "mkdir -p _build/html/slides && marp --input-dir slides --html -o _build/html/slides/", + "build-slides": "mkdir -p _build/html/slides && marp --input-dir slides --html -o _build/html/slides/ && rsync -am --include='*/' --include='*.jpg' --include='*.jpeg' --include='*.png' --include='*.gif' --include='*.svg' --exclude='*' content/ _build/html/content/", "build": "bun run build-book && bun run build-slides", "serve": "myst start", "clean": "rm -rf _build"