mirror of
https://github.com/harvard-edge/cs249r_book.git
synced 2026-11-09 10:39:41 -06:00
Vijay Janapa Reddi
4bec7f18e9
The Lab Guide PDF had no content of its own. guide/pdf/_quarto.yml listed ../modules/*.qmd, the same twenty files the website renders, plus preface, getting-started, the milestones, and the glossary. It was the website typeset. That made every module page serve two renderers at once, which is why the pages carry so much narrative: a page thin enough to be a good landing page made a poor PDF chapter. The book has since become the explanatory artifact, with a fixed structure per chapter (The Problem, The Idea, The Code, A Worked Trace, From TinyTorch to Production), and it covers preface, welcome and milestones 01-03 already. So the split is now the one the docs described all along, minus the duplicate: a website you do the work on, and a book that explains it. Removed: - guide/pdf/ (6 files) - the Lab Guide entry from the navbar; two PDF downloads remain - guide/Makefile's pdf and install-deps targets, and the pdf/_build bookkeeping; `all` now defaults to `site` - the build-guide job in tinytorch-update-pdfs.yml and build-pdf-guide in tinytorch-build-pdfs.yml, plus the download/inject steps in preview-dev and publish-live, the site-only preservation entry, and the summary rows that referenced the removed jobs Kept, because other things depend on them: - guide/tools/diagrams/svg-to-pdf.lua, which book/_quarto.yml borrows - guide/Makefile's `figures` target, which produces the sibling PDFs that filter needs Moved rather than deleted: apt-requirements.txt and tex-requirements.txt now live in book/, since the book is the only PDF built from this tree. The book gets its own Makefile carrying install-deps, and the workflow that used to run `make install-deps` in tinytorch/guide now runs it in tinytorch/book. book/index.qmd states the website-and-book pairing that replaces the "Two Pillars" section retired with guide/pdf/index.qmd. Verified: site builds, documented tito commands still resolve, all four workflows parse, and no reference to TinyTorch-Guide or build-guide remains anywhere in the tree.
117 lines
5.4 KiB
Makefile
117 lines
5.4 KiB
Makefile
# =============================================================================
|
|
# TinyTorch guide build
|
|
# =============================================================================
|
|
# Two Quarto projects share this directory:
|
|
# • the website (this directory's _quarto.yml, project type "website")
|
|
#
|
|
# Both consume the same chapter qmd files in modules/. Hand-authored SVG
|
|
# diagrams in assets/images/diagrams/ are the source-of-truth artifacts —
|
|
# edit them directly in Inkscape, Affinity, or a text editor (see
|
|
# tools/diagrams/STYLE.md for the visual convention). For the LaTeX
|
|
# build we convert each SVG to a sibling PDF via rsvg-convert; a small
|
|
# Lua filter (tools/diagrams/svg-to-pdf.lua) rewrites the qmd image
|
|
# refs from `.svg` → `.pdf` only for the PDF format, so the website
|
|
# keeps serving SVGs while the PDF embeds the pre-converted vector PDFs.
|
|
#
|
|
# Common entry points:
|
|
# make — alias for `make site`
|
|
# make site — render the website (HTML)
|
|
# make figures — only convert SVGs to PDFs (no render)
|
|
# make clean — remove caches + generated diagram PDFs
|
|
# make distclean — clean + remove rendered guide & website outputs
|
|
# make help — list all targets
|
|
# make check-tools — verify rsvg-convert + quarto are on PATH
|
|
#
|
|
# Dependencies:
|
|
# • quarto (https://quarto.org)
|
|
# • rsvg-convert (`brew install librsvg` on macOS,
|
|
# `apt-get install librsvg2-bin` on Debian/Ubuntu)
|
|
# =============================================================================
|
|
|
|
# Use bash + fail-fast pipelines so a broken sub-step actually fails the
|
|
# Make target rather than silently emitting a stale PDF.
|
|
SHELL := /bin/bash
|
|
.SHELLFLAGS := -eu -o pipefail -c
|
|
|
|
DIAGRAM_DIR := assets/images/diagrams
|
|
|
|
# Discover diagrams from the filesystem so adding a new SVG (drop a new
|
|
# file into $(DIAGRAM_DIR)) automatically gets picked up the next time
|
|
# `make figures` runs. We compute the .pdf list from the .svg list:
|
|
# SVGs are the source-of-truth, PDFs are the derived LaTeX-embed format.
|
|
SVGS := $(wildcard $(DIAGRAM_DIR)/*.svg)
|
|
PDFS := $(SVGS:.svg=.pdf)
|
|
|
|
# rsvg-convert flags:
|
|
# -f pdf emit PDF (otherwise it picks based on extension)
|
|
# --keep-aspect-ratio ensure no squashing if a viewBox is unusual
|
|
# We deliberately do NOT pass --width/--height — the SVG's own viewBox
|
|
# is the canvas size, and forcing a pixel size would defeat vector
|
|
# rendering downstream in LaTeX.
|
|
RSVG := rsvg-convert
|
|
RSVG_FLAGS := -f pdf --keep-aspect-ratio
|
|
|
|
QUARTO := quarto
|
|
|
|
# Treat every target below as phony except the actual file recipes.
|
|
.PHONY: all pdf site figures clean distclean help check-tools
|
|
|
|
all: site
|
|
|
|
help: ## Show this help.
|
|
@awk 'BEGIN {FS = ":.*##"; printf "Targets:\n"} \
|
|
/^[a-zA-Z_-]+:.*?##/ {printf " \033[36m%-14s\033[0m %s\n", $$1, $$2}' \
|
|
$(MAKEFILE_LIST)
|
|
|
|
# ── SVG → PDF conversion ──────────────────────────────────────────────
|
|
# Pattern rule: Make's automatic dependency on $< means a touched SVG
|
|
# re-converts only the affected PDF — the build is incremental over
|
|
# diagram edits.
|
|
$(DIAGRAM_DIR)/%.pdf: $(DIAGRAM_DIR)/%.svg | check-tools
|
|
@$(RSVG) $(RSVG_FLAGS) -o $@ $<
|
|
@printf " rsvg → %s\n" "$@"
|
|
|
|
figures: $(PDFS) ## Convert all SVG diagrams to PDF (for LaTeX embedding).
|
|
|
|
# ── Render targets ────────────────────────────────────────────────────
|
|
# `make pdf` is the canonical "rebuild the lab guide" command. It
|
|
# converts every SVG to PDF, then runs Quarto. The Lua filter in
|
|
# The book (../book) borrows guide/tools/diagrams/svg-to-pdf.lua, which rewrites
|
|
# .svg → .pdf for the PDF format only, so the sibling PDFs are still needed.
|
|
#
|
|
# Quarto's post-render cleanup step exits non-zero because the book
|
|
# project reads chapters at `../modules/...` — outside its own project
|
|
# root — so Quarto refuses to remove the auxiliary `_files/` directories
|
|
# left behind there. XeLaTeX has already written the PDF by that point,
|
|
# so we mirror the CI pattern (.github/workflows/tinytorch-build-pdfs.yml):
|
|
# run Quarto, capture its exit code, then *verify the PDF exists* and
|
|
# treat the cleanup error as benign only if it does. If the PDF is
|
|
# missing, fail loudly — that's a real build failure.
|
|
|
|
# Single canonical PDF output — the ONLY shippable file.
|
|
# Verify no duplicate copies exist.
|
|
site: ## Build the website (HTML).
|
|
@$(QUARTO) render
|
|
|
|
# ── Maintenance ───────────────────────────────────────────────────────
|
|
clean: ## Remove Quarto caches + generated diagram PDFs + any stray top-level PDF.
|
|
@rm -rf _tmp modules/*_files
|
|
@rm -rf *_files
|
|
@rm -f $(DIAGRAM_DIR)/*.pdf
|
|
@echo " cleaned caches, generated diagram PDFs, stray *_files dirs, and stray PDF copies"
|
|
|
|
distclean: clean ## Also remove website output.
|
|
@rm -rf _site
|
|
@echo " removed rendered outputs"
|
|
|
|
check-tools: ## Verify rsvg-convert + quarto are on PATH.
|
|
@command -v $(RSVG) >/dev/null 2>&1 || { \
|
|
echo "ERROR: $(RSVG) not found on PATH."; \
|
|
echo " macOS: brew install librsvg"; \
|
|
echo " Debian: apt-get install librsvg2-bin"; \
|
|
exit 1; }
|
|
@command -v $(QUARTO) >/dev/null 2>&1 || { \
|
|
echo "ERROR: $(QUARTO) not found on PATH."; \
|
|
echo " Install from https://quarto.org"; \
|
|
exit 1; }
|