Files

140 lines
4.9 KiB
Python

#!/usr/bin/env python3
"""Generate books/shared/STRUCTURE.md from the per-volume Quarto PDF configs.
The PDF config is the canonical chapter order ("Chapter order is
canonical"). This script derives the reading order from it so the manifest can
never disagree with what actually builds. Never hand-edit STRUCTURE.md.
python3 binder/tools/scripts/structure/gen_structure.py [--check]
"""
from __future__ import annotations
import argparse
import re
import sys
from pathlib import Path
REPO = Path(__file__).resolve().parents[4]
QUARTO = REPO / "books"
CONTENTS = QUARTO
OUT = CONTENTS / "shared" / "STRUCTURE.md"
VOLUMES = {
"vol1": "Volume I: Introduction to Machine Learning Systems",
"vol2": "Volume II: Scaling Machine Learning Systems",
"vol3": "Volume III: Agentic Machine Learning Systems",
"vol4": "Volume IV: Physical AI Systems",
}
QMD_RE = re.compile(r"(?<![\w/.-])(vol[0-9])/([A-Za-z0-9_./-]+\.qmd)")
def entries_for(vol: str) -> list[str]:
"""Reading order for one volume, from its PDF config, first occurrence wins."""
cfg = QUARTO / "config" / f"_quarto-pdf-{vol}.yml"
if not cfg.exists():
return []
seen: list[str] = []
for line in cfg.read_text(encoding="utf-8").splitlines():
stripped = line.strip()
# Only render/chapter/appendix list items, not navbar hrefs or comments.
if not stripped.startswith("- ") or stripped.startswith("#"):
continue
m = QMD_RE.search(stripped)
if m and m.group(1) == vol:
rel = m.group(2)
if rel not in seen:
seen.append(rel)
return seen
def classify(rel: str) -> str:
"""Return the manifest kind of a volume-relative path: frontmatter, backmatter, part, index, or chapter."""
top = rel.split("/", 1)[0]
if top == "frontmatter":
return "frontmatter"
if top == "backmatter":
return "backmatter"
if top == "parts":
return "part"
if rel == "index.qmd":
return "index"
return "chapter"
def render() -> str:
"""Build the STRUCTURE.md text: a fixed preamble, then a numbered reading-order table for each volume with a PDF config."""
lines = [
"# Content Structure",
"",
"<!-- GENERATED FILE. Do not edit by hand. -->",
"<!-- Regenerate: python3 binder/tools/scripts/structure/gen_structure.py -->",
"",
"Chapter order is derived from each volume's Quarto PDF config",
"(`books/config/_quarto-pdf-<vol>.yml`), which is the canonical",
"reading order. This file is a readable summary of that order.",
"",
"## Shared skeleton",
"",
"Every volume uses the same layout:",
"",
"```",
"books/<vol>/",
"├── index.qmd volume home",
"├── README.md volume readme",
"├── frontmatter/ *.qmd",
"├── parts/ <name>_principles.qmd + summaries.yml",
"├── <chapter>/ <chapter>.qmd + images/",
"└── backmatter/ references.qmd, appendix_*.qmd, glossary/",
"```",
"",
"The load-bearing invariant is `<chapter>/<chapter>.qmd`: a chapter directory",
"and its main file share a name. `binder/cli/commands/build.py` relies on it,",
"and `binder/tests/test_content_structure.py` enforces it.",
"",
]
for vol, title in VOLUMES.items():
rels = entries_for(vol)
if not rels:
continue
chapters = [r for r in rels if classify(r) == "chapter"]
lines += [f"## {title} (`{vol}`)", ""]
lines += [f"{len(chapters)} chapters. Reading order:", "", "| # | Kind | Path |", "|---:|---|---|"]
n = 0
for rel in rels:
kind = classify(rel)
if kind == "chapter":
n += 1
num = str(n)
else:
num = ""
lines.append(f"| {num} | {kind} | `{rel}` |")
lines.append("")
# Exactly one trailing newline, matching the end-of-file-fixer hook.
while lines and not lines[-1]:
lines.pop()
return "\n".join(lines) + "\n"
def main() -> int:
"""Write STRUCTURE.md, or with ``--check`` compare it to the rendered text and return 1 if stale."""
ap = argparse.ArgumentParser()
ap.add_argument("--check", action="store_true", help="fail if STRUCTURE.md is stale")
args = ap.parse_args()
new = render()
if args.check:
old = OUT.read_text(encoding="utf-8") if OUT.exists() else ""
if old != new:
print("STRUCTURE.md is stale. Regenerate with:", file=sys.stderr)
print(" python3 binder/tools/scripts/structure/gen_structure.py", file=sys.stderr)
return 1
print("STRUCTURE.md is current.")
return 0
OUT.write_text(new, encoding="utf-8")
print(f"Wrote {OUT.relative_to(REPO)}")
return 0
if __name__ == "__main__":
raise SystemExit(main())