demolab-cli 2.3.0__tar.gz → 2.5.0__tar.gz

{demolab_cli-2.3.0 → demolab_cli-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: demolab-cli
-Version: 2.3.0
+Version: 2.5.0
 Summary: Lab notebook for computational science: Python tools produce per-run artifacts; Typst publishes them as a web bundle, per-entry PDFs, and a book.
 Project-URL: Homepage, https://github.com/eoinmurray/demolab
 Project-URL: Changelog, https://github.com/eoinmurray/demolab/blob/main/demolab_cli/CHANGELOG.md
@@ -35,7 +35,7 @@ Description-Content-Type: text/markdown
 
 > **Coding agent setting someone up?** Run `uvx demolab-cli docs GETTING-STARTED`, read the file it prints, and follow it strictly, step by step. *(Human, setting up by hand? See [Quickstart](#quickstart).)*
 
-You write a model or experiment once as a small program. Demolab runs it, captures everything it produced, stamps it with the exact code version, and publishes a clean page — figures, numbers, and real typeset maths — to both the web and PDF. The numbers on the page are read from the run, so they can't drift. You drive it all by talking to a coding agent; there's no web development or build config to touch.
+You write a model or experiment once as a small program. Demolab runs it, captures everything it produced, stamps it with the exact code version, and publishes a clean page — figures, numbers, and real typeset maths — to the web and, by default, PDF. The numbers on the page are read from the run, so they can't drift. You drive it all by talking to a coding agent; there's no web development or build config to touch.
 
 ## Quickstart
 
@@ -78,7 +78,7 @@ Open your lab in your agent and say a runbook's name — it follows that runbook
 
 ## How it works
 
-One decoupled loop: **a tool computes → drops data → an experiment writes it up → the site publishes it.** Every run records its exact parameters and the git commit it came from (stamped on the page), and tables read their numbers straight from the run — so prose and results can't disagree. A single Typst pass emits a website, a PDF per entry, and a book, all sharing the same live numbers.
+One decoupled loop: **a tool computes → drops data → an experiment writes it up → the site publishes it.** Every run records its exact parameters and the git commit it came from (stamped on the page), and tables read their numbers straight from the run — so prose and results can't disagree. A single Typst pass emits a website and, unless `pdfs: false` is set in `demolab.yaml`, a PDF per entry and a book, all sharing the same live numbers.
 
 The detail lives in the guides (in a lab: `demolab docs <NAME>`; in this repo, the files under `demolab_cli/guides/`):
 

{demolab_cli-2.3.0 → demolab_cli-2.5.0}/README.md

@@ -4,7 +4,7 @@
 
 > **Coding agent setting someone up?** Run `uvx demolab-cli docs GETTING-STARTED`, read the file it prints, and follow it strictly, step by step. *(Human, setting up by hand? See [Quickstart](#quickstart).)*
 
-You write a model or experiment once as a small program. Demolab runs it, captures everything it produced, stamps it with the exact code version, and publishes a clean page — figures, numbers, and real typeset maths — to both the web and PDF. The numbers on the page are read from the run, so they can't drift. You drive it all by talking to a coding agent; there's no web development or build config to touch.
+You write a model or experiment once as a small program. Demolab runs it, captures everything it produced, stamps it with the exact code version, and publishes a clean page — figures, numbers, and real typeset maths — to the web and, by default, PDF. The numbers on the page are read from the run, so they can't drift. You drive it all by talking to a coding agent; there's no web development or build config to touch.
 
 ## Quickstart
 
@@ -47,7 +47,7 @@ Open your lab in your agent and say a runbook's name — it follows that runbook
 
 ## How it works
 
-One decoupled loop: **a tool computes → drops data → an experiment writes it up → the site publishes it.** Every run records its exact parameters and the git commit it came from (stamped on the page), and tables read their numbers straight from the run — so prose and results can't disagree. A single Typst pass emits a website, a PDF per entry, and a book, all sharing the same live numbers.
+One decoupled loop: **a tool computes → drops data → an experiment writes it up → the site publishes it.** Every run records its exact parameters and the git commit it came from (stamped on the page), and tables read their numbers straight from the run — so prose and results can't disagree. A single Typst pass emits a website and, unless `pdfs: false` is set in `demolab.yaml`, a PDF per entry and a book, all sharing the same live numbers.
 
 The detail lives in the guides (in a lab: `demolab docs <NAME>`; in this repo, the files under `demolab_cli/guides/`):
 

{demolab_cli-2.3.0 → demolab_cli-2.5.0}/demolab_cli/AGENT.md

@@ -3,7 +3,7 @@
 You are operating a **demolab lab**: an agent-operated lab notebook for computational
 science. The loop: a tool computes → drops data under `artifacts/data/<id>/` → an
 experiment writes it up in `writings/<id>.typ` → `demolab build` publishes it all as a
-website, per-entry PDFs, and a book. Every number on a page is read from the run that
+website, plus per-entry PDFs and a book unless the lab opts out. Every number on a page is read from the run that
 produced it — nothing is hand-typed, so prose and results can't drift.
 
 This manual ships inside the `demolab-cli` package and is printed by `demolab docs`, so it
@@ -13,7 +13,7 @@ short.
 ## The layout, in one breath
 
 `tools/` (reusable science), `experiments/` (runners), `writings/` (the .typ writeups),
-`artifacts/` (the committed record: `data/` + `pdfs/`; `site/` is a gitignored build),
+`artifacts/` (the committed record: `data/` + optional `pdfs/`; `site/` is a gitignored build),
 `demolab.yaml` (branding — and the lab-root marker every `demolab` command walks up to).
 The engine lives in the installed package, not the lab; the gitignored `.demolab/` dir is
 machine-managed staging. Full tree: `demolab docs STRUCTURE`.
@@ -71,7 +71,7 @@ guide covers it, ground your answer in it — cite it or offer to start it.
 `demolab` lists them all. The loop: `uv run python experiments/expNNN.py` (run an experiment
 end-to-end — run the runner directly, there's no `demolab run` wrapper) · `demolab dev`
 (live-preview server — have the *user* run it in their own terminal) · `demolab build`
-(complete site + PDFs) · `demolab build <id>` (one entry PDF) · `demolab test`. Preview
+(site + optional PDFs) · `demolab build <id>` (one entry PDF, when enabled) · `demolab test`. Preview
 PDFs stay in the ignored site tree; run the complete build before publishing. Reference data ships in the package:
 `demolab docs STARTERS` (canonical first experiments — model file shapes on them, never copy
 blindly; `monte-carlo-pi` is the default) and `demolab docs DEMO` (the published docs site's

{demolab_cli-2.3.0 → demolab_cli-2.5.0}/demolab_cli/CHANGELOG.md

@@ -13,6 +13,23 @@ the runbook shows the entries between your version and the latest.
 
 ## [Unreleased]
 
+## [2.5.0] — 2026-08-23
+
+### Added
+- **PDF publishing can be disabled for web-only labs.** Set `pdfs: false` in
+  `demolab.yaml` to omit per-entry PDFs, the combined book, PDF links, and PDF-only slide
+  decks. Existing files under `artifacts/pdfs/` are preserved; the default remains enabled.
+
+## [2.4.0] — 2026-08-14
+
+### Added
+- **Collection articles can opt into a developer-documentation web theme.** Add `theme: docs`
+  to a collection in `demolab.yaml`; its article pages receive a technical sans/mono type system,
+  linked table-of-contents support, code and API-reference surfaces, and documentation-oriented
+  tables. Collection listings, experiments, PDFs, and the combined book retain the standard lab
+  presentation. The shipped demo includes a fictional Python SDK guide and API reference as a
+  complete worked example.
+
 ## [2.3.0] — 2026-08-07
 
 ### Added

demolab_cli-2.5.0/demolab_cli/VERSION

@@ -0,0 +1 @@
+2.5.0

{demolab_cli-2.3.0 → demolab_cli-2.5.0}/demolab_cli/build.py

@@ -1,4 +1,4 @@
-"""Discover writings/*.typ, write a JSON manifest, and compile all three targets.
+"""Discover writings/*.typ, write a JSON manifest, and compile the configured targets.
 
 build.py does only what Typst can't: it globs the filesystem (Typst has no directory
 listing) and orchestrates the compiler. It stages the engine's Typst surface into the lab
@@ -16,8 +16,8 @@ into artifacts/site/:
   pdfs/book.pdf         — every entry concatenated into one PDF (book mode)
 
 The site (artifacts/site/) is a self-contained build output (gitignored, deployed to
-Pages). The PDFs are also mirrored to the committed artifacts/pdfs/ as shareable
-deliverables.
+Pages). Unless `pdfs: false` is set in demolab.yaml, PDFs are also mirrored to the
+committed artifacts/pdfs/ as shareable deliverables.
 
 Each writings/<id>.typ exposes `#let meta = (...)` and `#let body = [...]`.
 Entries not yet in that convention are skipped (incremental migration).
@@ -49,6 +49,24 @@ SITE = ROOT / "artifacts" / "site"         # bundle output (HTML + mp4 + pdfs/),
 PDFS = ROOT / "artifacts" / "pdfs"         # committed copy of the PDFs (shareable)
 
 
+def pdfs_enabled() -> bool:
+    """Whether this lab publishes PDFs (default: yes).
+
+    demolab.yaml intentionally has no Python YAML dependency. This reads the one supported
+    top-level boolean directly; Typst remains the authority for the rest of the config.
+    """
+    config = ROOT / "demolab.yaml"
+    if not config.is_file():
+        return True
+    text = config.read_text(encoding="utf-8")
+    match = re.search(r"(?m)^pdfs:\s*(true|false)\s*(?:#.*)?$", text)
+    if match:
+        return match.group(1) == "true"
+    if re.search(r"(?m)^pdfs\s*:", text):
+        raise SystemExit("error: demolab.yaml 'pdfs' must be true or false")
+    return True
+
+
 def _find_typst() -> str:
     """The typst CLI — needs --features bundle,html (experimental). A lab-local install wins
     (.tools/bin — the no-package-manager fallback for locked-down machines), then PATH;
@@ -108,7 +126,8 @@ def discover_decks():
     return [p.name.removesuffix(".slide.typ") for p in sorted(WRITINGS.glob("*.slide.typ"))]
 
 
-def write_manifest(ids: list[str], deck_ids: list[str], broken: dict | None = None) -> None:
+def write_manifest(ids: list[str], deck_ids: list[str], broken: dict | None = None,
+                   *, publish_pdfs: bool = True) -> None:
     """Write temp/bundle/index.json — the id/asset lists the staged main.typ reads.
 
     This is the only place per-entry knowledge is assembled, and it's pure data (no Typst
@@ -132,6 +151,7 @@ def write_manifest(ids: list[str], deck_ids: list[str], broken: dict | None = No
     manifest = {
         "entries": entries,
         "decks": [{"id": d} for d in deck_ids],
+        "pdfs_enabled": publish_pdfs,
         "has_brand_config": (ROOT / "demolab.yaml").exists(),
         "has_landing": (ROOT / "landing.typ").exists(),
     }
@@ -180,13 +200,13 @@ def _error_excerpt(err: str, lines: int = 8) -> str:
     return err.strip() or "build failed"
 
 
-def compile_bundle(ids: list[str], deck_ids: list[str]) -> dict:
+def compile_bundle(ids: list[str], deck_ids: list[str], *, publish_pdfs: bool = True) -> dict:
     """Compile the whole bundle. If an entry fails (a missing figure, a Typst error), flag it and
     retry, so it renders as a stub page instead of taking the rest of the site down with it. Returns
     the {id: error} map of entries that were stubbed."""
     broken: dict = {}
     while True:
-        write_manifest(ids, deck_ids, broken=broken)
+        write_manifest(ids, deck_ids, broken=broken, publish_pdfs=publish_pdfs)
         proc = subprocess.run(
             typst_compile("--format", "bundle", "--features", "bundle,html",
                           "--root", str(ROOT), str(MAIN), str(SITE) + "/"),
@@ -275,11 +295,14 @@ def main() -> None:
         raise SystemExit("error: build accepts at most one entry id")
     stage()
     ids = discover()
+    publish_pdfs = pdfs_enabled()
     _warn_if_content_misplaced(ids)
     if entry_args:
+        if not publish_pdfs:
+            raise SystemExit("error: PDF publishing is disabled by demolab.yaml (pdfs: false)")
         compile_entry(entry_args[0], ids)
         return
-    deck_ids = discover_decks()
+    deck_ids = discover_decks() if publish_pdfs else []
     # Zero writings is a valid state (a freshly `demolab scaffold`-ed repo): main.typ renders
     # a friendly empty-state homepage, so we build rather than error.
     # Compile decks first so their PDFs exist for the asset embeds in main.typ (skip reuses the
@@ -288,18 +311,23 @@ def main() -> None:
         good_decks = [d for d in deck_ids if (DECKS / f"{d}.pdf").exists()]
     else:
         good_decks = compile_decks(deck_ids)
-    write_manifest(ids, good_decks)
+    write_manifest(ids, good_decks, publish_pdfs=publish_pdfs)
     SITE.mkdir(parents=True, exist_ok=True)
+    if not publish_pdfs:
+        # Bundle compilation updates named outputs but does not prune outputs from an earlier
+        # build. The site tree is regenerable, so remove stale PDFs before a web-only compile;
+        # the committed artifacts/pdfs/ record remains deliberately untouched.
+        shutil.rmtree(SITE / "pdfs", ignore_errors=True)
     if generate_only:
         print(f"wrote manifest for {len(ids)} entries: {', '.join(ids)}"
               + (f" + {len(good_decks)} decks: {', '.join(good_decks)}" if good_decks else ""))
         return
     # One bad entry (a missing figure, a Typst error) becomes a stub page instead of failing the
     # whole site — compile_bundle flags it and retries.
-    broken = compile_bundle(ids, good_decks)
+    broken = compile_bundle(ids, good_decks, publish_pdfs=publish_pdfs)
     good = [i for i in ids if i not in broken]
     # mirror the compiled PDFs (entries, book, and decks) to the committed artifacts/pdfs/
-    if not no_mirror:
+    if publish_pdfs and not no_mirror:
         PDFS.mkdir(parents=True, exist_ok=True)
         for pdf in sorted((SITE / "pdfs").glob("*.pdf")):
             shutil.copy(pdf, PDFS / pdf.name)
@@ -310,8 +338,9 @@ def main() -> None:
     print(f"  entries: {', '.join(good)}"
           + (f"  ·  decks: {', '.join(good_decks)}" if good_decks else "")
           + (f"  ·  ⚠ stubbed: {', '.join(sorted(broken))}" if broken else "")
-          + (f"  ·  pdfs -> {PDFS.relative_to(ROOT)}/" if not no_mirror
-             else "  ·  preview PDFs left untracked"))
+          + (f"  ·  pdfs -> {PDFS.relative_to(ROOT)}/" if publish_pdfs and not no_mirror
+             else "  ·  preview PDFs left untracked" if publish_pdfs
+             else "  ·  PDF publishing disabled"))
     summary = f"built {len(good)} entries" + (f" + {len(good_decks)} decks" if good_decks else "")
     if broken:
         summary += f", {len(broken)} stubbed"

{demolab_cli-2.3.0 → demolab_cli-2.5.0}/demolab_cli/cli.py

@@ -45,7 +45,7 @@ GROUPS: list[tuple[str, list[tuple[str, str]]]] = [
     ]),
     ("publishing", [
         ("dev", "🔥 Serve the site with hot-reload + in-browser build errors (--demo serves the shipped demo, add --landing for its landing page; PORT overrides the auto-picked 3000)"),
-        ("build", "📦 Build the whole bundle → artifacts/site/ (web) + artifacts/pdfs/ (PDFs + book)"),
+        ("build", "📦 Build the publication → artifacts/site/ (web) + optional artifacts/pdfs/"),
         ("slides", "🎞  Compile standalone Typst decks (writings/*.typ with no meta+body) to artifacts/pdfs/"),
         ("playground", "🎛  Launch the interactive Streamlit demo (http://localhost:8501)"),
     ]),

{demolab_cli-2.3.0 → demolab_cli-2.5.0}/demolab_cli/guides/GLOSSARY.md

@@ -10,13 +10,13 @@ RULES' `§N.M`) and listed alphabetically. Section references like `§4.3` point
 
 **G3 — Black box.** The installed `demolab-cli` package (the build engine, runbooks, guides, scaffold) plus the machine-managed `.demolab/` staging dir it materialises at the lab root. Pure upstream, never hand-edited; *"update demolab"* is a dependency bump (§3.1). Your customisation lives *outside* it, in `demolab.yaml` and your content.
 
-**G4 — Brand config.** The optional root `demolab.yaml`: wordmark, PDF titles, and the collection registry. Absent ⇒ engine defaults (§3.3, §6.5).
+**G4 — Lab config.** The optional root `demolab.yaml`: branding, collection registry, web themes, and the `pdfs` publishing switch. Absent keys use engine defaults (§3.3, §6.5).
 
-**G5 — Bundle.** The Typst multi-document output from one compile: the site, per-entry PDFs, and the book, all emitted together by `main.typ` (§5.2).
+**G5 — Bundle.** The Typst multi-document output from one compile: always the site and, unless disabled, per-entry PDFs and the book, all emitted by `main.typ` (§5.2).
 
 **G6 — Coding agent.** The AI assistant (Claude Code, Cursor, aider, …) that reads this repo and operates it: runs the toolchain, wires files, follows runbooks.
 
-**G7 — Collection.** A group of entries sharing a `collection:` slug in their `meta`. Entries are grouped by collection on the homepage; a slug title-cases by default, and `demolab.yaml` can give it a label/description/order (§6.5).
+**G7 — Collection.** A group of entries sharing a `collection:` slug in their `meta`. Entries are grouped by collection on the homepage; a slug title-cases by default, and `demolab.yaml` can give it a label/description/order plus an optional article web theme (§6.5).
 
 **G8 — Contract.** The file-based interface between a tool and an experiment: a tool writes a fixed set of files (§4.3), a runner reads them by running the tool's CLI (§4.5). It's language-neutral (§1.4).
 

{demolab_cli-2.3.0 → demolab_cli-2.5.0}/demolab_cli/guides/RULES.md

@@ -13,7 +13,7 @@ defined in [`GLOSSARY.md`](GLOSSARY.md).
 
 **1.1 — Python via `uv`.** Never call `python` / `python3` directly. Deps are pinned in the root `pyproject.toml` / `uv.lock`; run scripts with `uv run python <script>` (e.g. `uv run python tools/neuron/tool.py lif`); `uv sync` after pulling.
 
-**1.2 — Publishing via `typst`.** Use the `typst` CLI (an installed prerequisite, alongside `uv`). It compiles the site + PDFs (`demolab build` / `demolab dev`); the bundle build passes `--features bundle,html` (experimental, deliberately used here). Typst receives a deterministic creation timestamp (`SOURCE_DATE_EPOCH` overrides the engine default), so unchanged PDFs stay byte-identical within a stable toolchain. No Node/`bun` — demolab publishes entirely with Typst.
+**1.2 — Publishing via `typst`.** Use the `typst` CLI (an installed prerequisite, alongside `uv`). It compiles the site + optional PDFs (`demolab build` / `demolab dev`); the bundle build passes `--features bundle,html` (experimental, deliberately used here). Typst receives a deterministic creation timestamp (`SOURCE_DATE_EPOCH` overrides the engine default), so unchanged PDFs stay byte-identical within a stable toolchain. No Node/`bun` — demolab publishes entirely with Typst.
 
 **1.3 — Prefer `demolab`.** Common commands are exposed through the `demolab` CLI — prefer `demolab <name>` (run `demolab` to list them). To check the toolchain *and* that the repo obeys these conventions, run the *Doctor the repo* runbook (*"doctor the repo"*).
 
@@ -72,17 +72,21 @@ The concrete annotated file tree is in [`STRUCTURE.md`](STRUCTURE.md); this sect
 
 **5.1 — Scratch vs record.** `temp/<tool>/<cmd>/` is scratch — gitignored, overwritten every run. The runner writes the rendered figure(s) + aggregated `numbers.json` (and any video) + a `run.sh` reproducer into **`artifacts/data/<id>/`**, which *is* committed. That folder is the publisher-neutral record: the single place the publisher reads from. (The tool's own `run.sh` stays in scratch `temp/`; the runner's is committed here.)
 
-**5.2 — Typst is the publisher.** `demolab build` globs `writings/*.typ` (and each entry's mp4s) into a JSON manifest (`temp/bundle/index.json`), stages the engine's static `main.typ` beside it, then compiles it (it reads the manifest) to **three targets in one pass** — no generated Typst source:
+**5.2 — Typst is the publisher.** `demolab build` globs `writings/*.typ` (and each entry's mp4s) into a JSON manifest (`temp/bundle/index.json`), stages the engine's static `main.typ` beside it, then compiles it (it reads the manifest) to the web and, by default, two PDF targets in one pass — no generated Typst source:
 - **Web** — `artifacts/site/`: `index.html` (entries grouped by collection, §6.5), `all.html` (every entry, newest first), and an HTML page per entry (figures inline, videos play, math as MathML, styled by the engine's stylesheet).
 - **Per-entry PDFs** — `artifacts/site/pdfs/<id>.pdf`.
 - **Book** — `artifacts/site/pdfs/book.pdf`: every entry, with a table of contents.
 
-For a PDF-only editing loop, `demolab build <id>` updates just
+Set the top-level `pdfs: false` in `demolab.yaml` for a web-only lab. The build then omits
+both PDF targets, every PDF link, and PDF-only slide decks. It does not delete existing
+files under `artifacts/pdfs/`; omitting the key or setting it to `true` preserves the default.
+
+When PDFs are enabled, `demolab build <id>` updates just
 `artifacts/pdfs/<id>.pdf`; it deliberately leaves the site and `book.pdf` untouched.
 `demolab dev` refreshes the complete ignored preview site without mirroring preview PDFs into
 the tracked publication directory. Run bare `demolab build` before publishing.
 
-**5.3 — What's committed.** PDFs are mirrored to the committed, shareable `artifacts/pdfs/`. `artifacts/site/` is a gitignored build output (CI regenerates + deploys it to Pages). CI does **not** run the experiments, so `artifacts/data/` **must** be committed — that record, not the ephemeral `temp/`, is what reaches the site.
+**5.3 — What's committed.** When enabled, PDFs are mirrored to the committed, shareable `artifacts/pdfs/`. `artifacts/site/` is a gitignored build output (CI regenerates + deploys it to Pages). CI does **not** run the experiments, so `artifacts/data/` **must** be committed — that record, not the ephemeral `temp/`, is what reaches the site.
 
 **5.4 — Numbers can't drift.** Each `writings/<id>.typ` reads its own bundle natively — `json("/artifacts/data/<id>/numbers.json")`, `#image("/artifacts/data/<id>/fig.png")` (compiled with `--root` at the repo root) — so the numbers and figures come straight from the run.
 
@@ -109,6 +113,19 @@ Numbers must come from the run (§5.4) — never hand-type a literal that could
 
 **6.5a — Curated reading order.** An optional integer `order:` in a writing's `meta` marks its collection as *curated*: that collection's page lists entries by `order` ascending (unranked entries trail, in id order) instead of the default status-then-newest sort. Use it when a collection should read as a sequence — a documentation arc, a course, a serial — and leave it off for a chronological log of results. If you rank one entry in a collection, rank them all; a half-ranked collection reads as an accident.
 
+**6.5b — Developer-documentation articles.** A registered collection may set `theme: docs` to give its **article web pages only** demolab's built-in developer-documentation treatment: technical sans/mono typography, cool slate surfaces, documentation tables, code panels, and API-reference accents. The collection listing, experiment pages in the same collection, per-entry PDFs, and combined book retain the standard lab design. `docs` is currently the only built-in theme:
+
+```yaml
+collection-order: [python-sdk]
+collections:
+  python-sdk:
+    label: Python SDK
+    description: Guides and API reference for the Python package.
+    theme: docs
+```
+
+The theme styles ordinary Typst headings, prose, code, and tables automatically. A documentation article may add HTML-only `docs-toc`, `docs-note`, and `api-signature` elements for the richer components demonstrated by the shipped `ar028` example; keep a meaningful plain Typst structure around them so the article remains useful in PDF form.
+
 **6.6 — Citations & references.** Cite prior work with two `lib.typ` helpers, so numbering, linking, and the web popover all come for free — never hand-type a bracket or a manual list (HOUSESTYLE H24). Import both: `#import "/.demolab/lib.typ": cite, reference-list`.
 
 - **Inline** — `#cite(1, 2)` renders `[1, 2]`. The numbers are **author-managed** (you pass them), so there's no `.bib` file to keep in sync. On the web each number links to its entry.

{demolab_cli-2.3.0 → demolab_cli-2.5.0}/demolab_cli/guides/STRUCTURE.md

@@ -30,7 +30,7 @@ my-lab/
 │   └── arNNN.slide.typ       a deck — Touying slides → standalone PDF      [G9]
 ├── artifacts/              the committed record of every run              [§5]
 │   ├── data/<id>/            figures + numbers.json + run.sh (+ any mp4) — the publisher-neutral record  [§5.1, G18]
-│   ├── pdfs/                 compiled PDFs (per entry + book.pdf) — shareable                    [§5.3]
+│   ├── pdfs/                 optional compiled PDFs (per entry + book.pdf) — shareable           [§5.3]
 │   └── site/                 the built web site — GITIGNORED (CI rebuilds + deploys it)          [§5.3]
 ├── demolab.yaml            branding + collections config — and the LAB MARKER the CLI walks up to  [§3.3, §6.5, G4]
 ├── HOUSESTYLE.local.md     optional — your house-style overrides (extend/replace)  [§3.3]
@@ -67,7 +67,7 @@ lives in the installed `demolab-cli` package (site-packages), reached via `demol
 
 **S5 — The package vs your stuff.** The engine is the installed `demolab-cli` package — you never hand-edit it, and updating it is a dependency bump (§3.1). The gitignored `.demolab/` staging dir is the CLI's, not yours (§3.2). Everything else in the tree is yours: `tools/`, `experiments/`, `writings/`, `artifacts/`, `demolab.yaml`, and the root stubs `demolab init` laid down (§3.3).
 
-**S6 — Where the build goes.** `demolab build` globs `writings/*.typ` into `temp/bundle/index.json`, stages the engine's `main.typ` beside it, and compiles it to three targets in one pass: the web site → `artifacts/site/`, per-entry PDFs + `book.pdf` → `artifacts/site/pdfs/` (mirrored to `artifacts/pdfs/`). `demolab build <id>` instead updates only `artifacts/pdfs/<id>.pdf`; `demolab dev` keeps preview PDFs in the ignored site tree and never mirrors them. On an empty (freshly-initialised) tree the complete build still succeeds — it emits a single `index.html` with a friendly empty state, and skips `all.html`/collection pages/`book.pdf`. CI deploys `artifacts/site/` to GitHub Pages (§5.2, §5.3).
+**S6 — Where the build goes.** `demolab build` globs `writings/*.typ` into `temp/bundle/index.json`, stages the engine's `main.typ` beside it, and compiles the web site → `artifacts/site/`. By default it also emits per-entry PDFs + `book.pdf` under `artifacts/site/pdfs/` and mirrors them to `artifacts/pdfs/`; `pdfs: false` in `demolab.yaml` makes the build web-only and omits PDF-only decks. `demolab build <id>` updates only `artifacts/pdfs/<id>.pdf` when PDFs are enabled; `demolab dev` never mirrors preview PDFs. On an empty tree the build emits a friendly `index.html` and skips the other documents. CI deploys `artifacts/site/` to GitHub Pages (§5.2, §5.3).
 
 ## Scaffolding
 

{demolab_cli-2.3.0 → demolab_cli-2.5.0}/demolab_cli/runbooks/GETTING-STARTED.md

@@ -182,8 +182,10 @@ freestyling, not following this runbook.
    tagline, book/PDF title (defaults from the name), and **author + contact** (offer to pull
    from git config — they render as a byline under the homepage title and an
    `<meta name="author">`; contact, if given, links the byline). The engine defaults any key
-   you omit and updates never touch it; `demolab dev` hot-reloads, so they watch it change. Deeper
-   theming (`style.css`, `favicon.svg`) lives inside the engine package — leave it as advanced.
+   you omit and updates never touch it; `demolab dev` hot-reloads, so they watch it change. If an
+   article collection is developer documentation, offer its built-in `theme: docs` treatment
+   (RULES §6.5b); it affects only that collection's article web pages. Deeper theming
+   (`style.css`, `favicon.svg`) lives inside the engine package — leave it as advanced.
 
 5. **Publish to GitHub Pages?** *"Free, unless the repo is private."* Default yes; if no, skip —
    it all works locally. If yes: create + push a GitHub repo (`gh`), run `demolab deploy-setup`

{demolab_cli-2.3.0 → demolab_cli-2.5.0}/demolab_cli/scaffold/demo/demolab.yaml

@@ -7,8 +7,12 @@ book-title: Demolab — the book
 contents-title: Demolab — contents
 description: A lab notebook for computational science — reproducible results, published and citable.
 
-collection-order: [documentation]
+collection-order: [documentation, theme-demo]
 collections:
   documentation:
     label: Documentation
     description: "How demolab works, in reading order: what it is and why, setting up, the contract, the mechanics of experiments and writeups, and running the lab day to day."
+  theme-demo:
+    label: Developer docs theme
+    description: "A single-page showroom for the optional developer-documentation collection theme."
+    theme: docs

{demolab_cli-2.3.0 → demolab_cli-2.5.0}/demolab_cli/scaffold/demo/writings/ar025.typ

@@ -51,7 +51,10 @@
   work: an unregistered slug is simply title-cased for display (`neuron-models` becomes
   "Neuron Models"). The `collections:` map in `demolab.yaml` upgrades that: per slug, a
   `label` (the display name) and a `description` (shown under the label on the homepage
-  and at the top of the collection's own page).
+  and at the top of the collection's own page). A collection can also set `theme: docs`
+  to give only its article web pages a light developer-documentation treatment. Collection
+  listings, experiment pages, standalone PDFs, and the combined book keep the standard lab
+  design. `docs` is currently the only built-in theme.
 
   `collection-order:` is a list of slugs setting the homepage order. Collections you leave
   out of the list still appear; they trail after the listed ones. Two special cases:
@@ -90,11 +93,15 @@
   contents-title: Demolab — contents
   description: A lab notebook for computational science — reproducible results, published and citable.
 
-  collection-order: [documentation, slides]
+  collection-order: [documentation, theme-demo, slides]
   collections:
     documentation:
       label: Documentation
       description: "How demolab works, in reading order: what it is and why, setting up, the contract, the mechanics of experiments and writeups, and running the lab day to day."
+    theme-demo:
+      label: Developer docs theme
+      description: "A single-page showroom for the optional developer-documentation collection theme."
+      theme: docs
     slides:
       label: Talks & slides
       description: Deck PDFs from talks — paged-only, linked as PDF.

demolab_cli-2.5.0/demolab_cli/scaffold/demo/writings/ar028.typ

@@ -0,0 +1,148 @@
+#let meta = (
+  title: "LatticeCache Python SDK",
+  date: "2026-08-14",
+  description: "Fake developer documentation and API reference for a fictional Python caching library.",
+  collection: "theme-demo",
+  status: "final",
+)
+
+#let body = [
+  LatticeCache is a fictional Python library for caching deterministic function calls on disk.
+  It is intentionally small, typed, and boring: the same inputs produce the same cache key, and
+  expired values disappear without ceremony.
+
+  #context if target() == "html" {
+    html.elem("nav", attrs: (class: "docs-toc", "aria-label": "On this page"), {
+      html.elem("p", attrs: (class: "docs-toc-title"), [On this page])
+      html.elem("ul", {
+        html.elem("li", html.elem("a", attrs: (href: "#installation"), [Installation]))
+        html.elem("li", html.elem("a", attrs: (href: "#quick-start"), [Quick start]))
+        html.elem("li", html.elem("a", attrs: (href: "#configuration"), [Configuration]))
+        html.elem("li", html.elem("a", attrs: (href: "#api-reference"), [API reference]))
+        html.elem("li", html.elem("a", attrs: (href: "#cache"), [`Cache`]))
+        html.elem("li", html.elem("a", attrs: (href: "#cached"), [`cached`]))
+      })
+    })
+  }
+
+  == Installation
+
+  LatticeCache requires Python 3.11 or later. Install it from the imaginary package index:
+
+  ```sh
+  pip install latticecache
+  ```
+
+  #context if target() == "html" {
+    html.elem("aside", attrs: (class: "docs-note"), [
+      *Demo package.* `latticecache` does not exist. This page is sample content for demolab's
+      optional article treatment, not advice to paste mysterious packages into your terminal.
+    ])
+  }
+
+  == Quick start
+
+  Create one cache and call `get_or_set` with a stable key. The factory runs only when no live
+  value exists.
+
+  ```python
+  from datetime import timedelta
+  from latticecache import Cache
+
+  cache = Cache(".cache/weather")
+
+  forecast = cache.get_or_set(
+      "madrid:2026-08-14",
+      factory=lambda: fetch_forecast("Madrid"),
+      ttl=timedelta(minutes=15),
+  )
+  ```
+
+  Values are encoded as JSON by default. Supply a codec when storing dataclasses, NumPy arrays,
+  or other objects that JSON cannot represent.
+
+  == Configuration
+
+  #table(
+    columns: (1.1fr, 1fr, 2.3fr),
+    [*Option*], [*Default*], [*Meaning*],
+    [`namespace`], [`"default"`], [Prefix used to isolate cache keys],
+    [`max_bytes`], [`256 MiB`], [Soft size limit checked after each write],
+    [`serializer`], [`"json"`], [Built-in `json`, `text`, or a custom codec],
+    [`read_only`], [`False`], [Allow reads but never create or refresh entries],
+  )
+
+  Configuration may be passed to `Cache` directly or loaded from `pyproject.toml` under
+  `[tool.latticecache]`. Constructor arguments win when both are present.
+
+  == API reference
+
+  === `Cache`
+
+  #context if target() == "html" {
+    html.elem("div", attrs: (class: "api-signature"), [
+      `class latticecache.Cache(path, *, namespace="default", max_bytes=268435456, read_only=False)`
+    ])
+  }
+
+  A filesystem-backed cache. Creating an instance makes its directory lazily on the first write;
+  constructing a read-only cache never changes the filesystem.
+
+  ==== Parameters
+
+  #table(
+    columns: (1fr, 1fr, 2.4fr),
+    [*Name*], [*Type*], [*Description*],
+    [`path`], [`str | Path`], [Directory containing cached values and metadata],
+    [`namespace`], [`str`], [Logical partition included in every derived key],
+    [`max_bytes`], [`int`], [Approximate limit before least-recently-used eviction],
+    [`read_only`], [`bool`], [Disable writes, refreshes, and eviction],
+  )
+
+  ==== `Cache.get_or_set`
+
+  #context if target() == "html" {
+    html.elem("div", attrs: (class: "api-signature"), [
+      `get_or_set(key, factory, *, ttl=None) -> Any`
+    ])
+  }
+
+  Return the live value stored under `key`. If the key is absent or expired, call `factory`,
+  store its result atomically, and return the new value.
+
+  - *Raises `ReadOnlyMiss`* when a read-only cache has no live value.
+  - *Raises `EncodeError`* when the configured serializer rejects the factory result.
+  - The factory's own exceptions pass through unchanged and are never cached.
+
+  ==== `Cache.invalidate`
+
+  #context if target() == "html" {
+    html.elem("div", attrs: (class: "api-signature"), [`invalidate(key) -> bool`])
+  }
+
+  Remove one key. Returns `true` when an entry existed and `false` when there was nothing to do.
+
+  === `cached`
+
+  #context if target() == "html" {
+    html.elem("div", attrs: (class: "api-signature"), [
+      `latticecache.cached(cache, *, ttl=None, key=None) -> Callable`
+    ])
+  }
+
+  Decorate a deterministic function. By default, the key combines the function's qualified name,
+  its source fingerprint, and a canonical encoding of positional and keyword arguments.
+
+  ```python
+  from latticecache import Cache, cached
+
+  cache = Cache(".cache/models", namespace="v2")
+
+  @cached(cache, ttl=3600)
+  def load_model(model_id: str, *, quantized: bool = False):
+      return download_model(model_id, quantized=quantized)
+  ```
+
+  Mutable global state is not part of the derived key. Pass every input explicitly or provide a
+  custom `key` function; invisible dependencies and caches are natural enemies.
+]

{demolab_cli-2.3.0 → demolab_cli-2.5.0}/demolab_cli/scaffold/root/README.md

@@ -9,7 +9,7 @@ per-run artifacts; Typst publishes them as a website, per-entry PDFs, and a book
 uv sync              # install dependencies + the `demolab` command
 demolab dev          # live-preview the site at http://localhost:3000
 uv run python experiments/exp000.py   # run an experiment end-to-end
-demolab build        # build the site + PDFs into artifacts/
+demolab build        # build the site + optional PDFs into artifacts/
 ```
 
 Run `demolab` for the full command list. If you work with a coding agent, it reads
@@ -21,7 +21,7 @@ chat shows the menu.
 - `experiments/` — runners that stage `artifacts/data/<id>/` (figures + numbers)
 - `writings/` — the write-ups (`<id>.typ`), published by `demolab build`
 - `tools/` — reusable science shared by experiments
-- `artifacts/` — the committed record: `data/` per run, `pdfs/` compiled deliverables
+- `artifacts/` — the committed record: `data/` per run, optional `pdfs/` deliverables
 - `demolab.yaml` — branding + collections (also marks this directory as a lab)
 
 The engine ships in the `demolab-cli` package — nothing to vendor or maintain here.

{demolab_cli-2.3.0 → demolab_cli-2.5.0}/demolab_cli/scaffold/skeleton/demolab.yaml

@@ -14,6 +14,10 @@ description: A lab notebook for computational science — reproducible results,
 # author: Your Name
 # contact: you@example.com
 
+# PDF publishing is enabled by default. Disable it for a web-only lab; existing PDFs are
+# left untouched, and PDF-only slide decks are omitted from the site.
+# pdfs: false
+
 # Optional collaborative inline comments on web articles and experiments. Readers select text
 # and discuss it through Hypothesis accounts and groups; PDFs are unchanged. Set this lab-wide,
 # or omit it here and add `annotations: "hypothesis"` to selected writings' `meta` blocks.
@@ -26,12 +30,15 @@ description: A lab notebook for computational science — reproducible results,
 
 # Homepage collections. Entries are grouped by their `collection:` meta field; this
 # registry gives each collection a display label + description and sets the order. A
-# collection with no entry here still works — its slug is just title-cased.
+# collection with no entry here still works — its slug is just title-cased. Add
+# `theme: docs` to a collection whose articles should have a light developer-documentation
+# web treatment. Collection listings, experiments, and PDFs retain the standard design.
 collection-order: [documentation, neuron-models, mujoco, streamlit, slides]
 collections:
   documentation:
     label: Documentation
     description: "How demolab works: getting started, the always-on guides that set the conventions, and the on-demand runbooks the agent runs."
+    # theme: docs
   neuron-models:
     label: Neuron models
     description: Integrate-and-fire neurons and the membrane biophysics behind them.

{demolab_cli-2.3.0 → demolab_cli-2.5.0}/demolab_cli/slides.py

@@ -19,6 +19,8 @@ def is_bundle_entry(source: str) -> bool:
 
 
 def main() -> None:
+    if not build.pdfs_enabled():
+        raise SystemExit("error: PDF publishing is disabled by demolab.yaml (pdfs: false)")
     build.stage()  # a deck may import /.demolab/lib.typ (video, data-file, …)
     build.PDFS.mkdir(parents=True, exist_ok=True)
     found = failed = False