The Makefile was copying pdf/_build/TinyTorch-Guide.pdf up to
pdf/TinyTorch-Guide.pdf as "local-dev convenience" so `open
pdf/TinyTorch-Guide.pdf` would work. This created two copies of the
same artifact at different paths — confusing when the user asked which
was authoritative.
Simplify to a single source of truth at pdf/_build/TinyTorch-Guide.pdf:
- Makefile: remove the `cp "$(PDF_BUILD)" "$(PDF_OUT)"` step. PDF_OUT
now IS the _build path. Help text and distclean target updated
accordingly.
- tools/measure-pdf-images.py: default PDF path updated from
pdf/TinyTorch-Guide.pdf to pdf/_build/TinyTorch-Guide.pdf.
CI workflows (tinytorch-build-pdfs.yml and tinytorch-update-pdfs.yml)
already point at pdf/_build/TinyTorch-Guide.pdf from the earlier
consistency pass (commit 7d9eab7ed era), so they're unaffected.
Local dev uses `open pdf/_build/TinyTorch-Guide.pdf` or an `open`
wrapper — one extra path segment, zero ambiguity about which file is
the real artifact.
Codifies the 'iconic lab book' framing (SICP / K&R / Three Easy Pieces
/ H&P slot), voice register, project conventions (no mid-doc HRs, no
emoji in PDF body prose, conditional-content pattern for HTML cards,
{python} shortcode trap), the change-budget per chapter, and the
return-report format. Single source of truth for the parallel
chapter-by-chapter narrative-quality pass.
Filename avoids the existing **/*_REVIEW*.md gitignore pattern in
tinytorch/.gitignore (which excludes review-notes scratch files).
The tinytorch/site-legacy/ directory was the old Sphinx + Jupyter Book
project. After the Quarto migration:
- Live website builds from tinytorch/quarto/ (project: website)
- Lab Guide PDF builds from tinytorch/quarto/pdf/ (project: book)
- All five tinytorch CI workflows invoke `quarto render` only;
nothing calls jb / jupyter-book / sphinx-build anywhere.
site-legacy/ was kept around as documentation of the previous pipeline
but has zero live consumers (verified: ripgrep across .py/.yml/.yaml/
.sh/.qmd/.md/.json/.toml/.lua/Makefile finds no remaining references
outside the tree itself). 27 MB, 213 files removed.
Guard rails removed alongside the tree:
- .pre-commit-config.yaml: drop tinytorch/site-legacy/ from the
check-internal-links exclusion block (no longer needed).
- tinytorch/quarto/tools/measure-pdf-images.py: drop the
`"site-legacy" in parts` skip from both the source-image index
and the .qmd index (2 occurrences).
- .github/workflows/tinytorch-build-pdfs.yml: drop the "legacy
jupyter-book pipeline ... is retired" historical comment.
- tinytorch/quarto/pdf/_quarto.yml: drop the "Replaces the legacy
jupyter-book + XeLaTeX pipeline" header comment and the
"palette mirrors site-legacy/_config_pdf.yml" note (the Quarto
config is now the canonical source for the brand palette).
Documentation cleanup:
- shared/styles/BRAND.md: repoint the broken
`tinytorch/site/_static/custom.css` reference at the live Quarto
SCSS files (style.scss + dark-mode.scss).
Quarto is now the sole TinyTorch publishing engine.
Capture the design lessons from the visual audit so future hand-authored
diagrams don't recreate the same problems we just fixed:
- Layout & topology section: 8 explicit rules covering arrows
(straight only — H/V/short diagonal), forbidden patterns (L-shapes,
bezier feedback wraps), N→1 fan-in (widen the target box, don't
bend the arrows), arrowhead clustering (spread across the edge),
and a planarity preference.
- Allowed exceptions: documented the three patterns that intentionally
break some rules — the "Next Batch" cycle indicator, panel-less
computation examples (e.g. broadcasting), and panel-less layered
stacks (e.g. Code → Backend → Hardware).
- Canvas section: replaced the fixed `0 0 680 360` viewBox with a
sizing recipe (size to content + ~10–20px). Added explicit rule
that the outer panel rect must enclose all nodes with ~20px padding.
- Workflow tip: visual audit step (rsvg-convert → PNG preview) is
now part of the add-a-diagram and edit-a-diagram instructions.
- Coordinate convention note: documented why every existing SVG wraps
content in `<g transform="translate(0,-50)">` (legacy generator
margin) so future edits stay consistent.
Brings the TinyTorch lab guide's Quarto project in line with
book/quarto/, the only other in-tree Quarto publication that builds
both web and PDF outputs from a single source. The previous name had
three redundancies:
- already under tinytorch/, so "site-" prefix wasn't disambiguating
- also produces the PDF lab guide, so "site-" was misleading
- the top-level site/ dir made "site-quarto" read as "the site's
quarto config" rather than "the tinytorch site, in quarto"
After this rename the convention is straightforward:
book/quarto/ -> the textbook (web + PDF)
tinytorch/quarto/ -> the TinyTorch lab guide (web + PDF)
mlsysim/docs/ -> mlsysim API reference (kept as docs/, since it
really is API reference, not a publication)
Touches 7 GitHub workflows, both .gitignore files, the rename target's
own self-references (Makefile, _quarto.yml configs, STYLE.md,
measure-pdf-images.py), and 6 copies of subscribe-modal.js plus a few
shared scripts/configs whose comments documented the old path.
Verified: rebuilt pdf/TinyTorch-Guide.pdf (2.1M) cleanly from the new
location with 'make pdf' from tinytorch/quarto/.
