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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: demolab-cli
-Version: 2.2.1
+Version: 2.3.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

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

@@ -13,6 +13,14 @@ the runbook shows the entries between your version and the latest.
 
 ## [Unreleased]
 
+## [2.3.0] — 2026-08-07
+
+### Added
+- **Optional collaborative inline annotations with Hypothesis.** Set `annotations: hypothesis`
+  lab-wide in `demolab.yaml` or `annotations: "hypothesis"` on one writing's `meta`; web readers
+  can highlight text and use Hypothesis threads and private groups, while PDFs remain unchanged.
+  The new `ar027` demo article documents the workflow and opts itself in as a live example.
+
 ## [2.2.1] — 2026-08-07
 
 ### Fixed

demolab_cli-2.3.0/demolab_cli/VERSION

@@ -0,0 +1 @@
+2.3.0

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

@@ -31,7 +31,7 @@ The concrete annotated file tree is in [`STRUCTURE.md`](STRUCTURE.md); this sect
 
 **3.2 — Machine-managed staging** (gitignored, owned by the CLI — never hand-edit): `.demolab/` at the lab root holds the few engine files Typst must read from inside the lab tree (`lib.typ`, the web assets, a `VERSION` stamp); every build refreshes it when the installed engine version changes. `temp/bundle/` holds the staged bundle root (`main.typ`) plus build scratch. Local edits to either are overwritten without warning — a customisation that seems to need them is a missing config knob (see 3.3, or propose it upstream).
 
-**3.3 — Your root overrides, optional** (root files the framework reads; never overwritten by updates): `demolab.yaml` (wordmark + PDF titles + collections — also the **lab marker**: the CLI finds the lab root by walking up to it, so don't delete it) and `HOUSESTYLE.local.md` (your house-style overrides, which extend or replace the default `HOUSESTYLE.md`; an agent reads it). Every key defaults ⇒ a minimal file is fine. The root stubs (`AGENTS.md`, `CLAUDE.md`, `README.md`, `pyproject.toml`, `.gitignore`, CI) are laid down once by `demolab init` and are yours from then on.
+**3.3 — Your root overrides, optional** (root files the framework reads; never overwritten by updates): `demolab.yaml` (wordmark + PDF titles + collections + optional web annotations — also the **lab marker**: the CLI finds the lab root by walking up to it, so don't delete it) and `HOUSESTYLE.local.md` (your house-style overrides, which extend or replace the default `HOUSESTYLE.md`; an agent reads it). Every key defaults ⇒ a minimal file is fine. The root stubs (`AGENTS.md`, `CLAUDE.md`, `README.md`, `pyproject.toml`, `.gitignore`, CI) are laid down once by `demolab init` and are yours from then on.
 
 **3.4 — User content** (100% the user's — freely deletable and replaceable): `tools/*`, `experiments/*` (runners, plus `playground.py` — the Streamlit demo, exempt from the contract), `writings/*` (`.typ` writeups), `artifacts/*` (`data/` per-run figures + `numbers.json`, `pdfs/` compiled PDFs; `artifacts/site/` is a gitignored build), `temp/*` (regenerable scratch).
 
@@ -118,6 +118,14 @@ Numbers must come from the run (§5.4) — never hand-type a literal that could
 
 See `ar006` for a worked example — ten references with DOIs, inline cites throughout, and the reference list at the foot of the body.
 
+**6.7 — Collaborative annotations are opt-in and web-only.** Set `annotations: hypothesis`
+in root `demolab.yaml` to embed the hosted Hypothesis client on every article and experiment,
+or put `annotations: "hypothesis"` in one writing's `meta` block to enable only that entry. An
+entry-level `annotations: none` disables a lab-wide setting. The client is never emitted into PDFs.
+Hypothesis owns annotation accounts, storage, private-group membership, anchoring, and threads;
+collaborators must choose their private group before posting if the discussion is not public. See
+demo article `ar027` for the complete setup and a live example.
+
 ## 7. Adding an experiment
 
 **7.1 — Tool subcommand.** Add a subcommand (or reuse one) in the relevant `tools/<tool>/tool.py`. Pass a `manifest` to `write_output` declaring the headline metrics (and a video, for a rendering tool).

demolab_cli-2.3.0/demolab_cli/scaffold/demo/writings/ar027.typ

@@ -0,0 +1,77 @@
+#let meta = (
+  title: "Discussing a writeup inline",
+  date: "2026-08-07",
+  description: "Optional Hypothesis annotations let collaborators highlight a passage in a web article or experiment and discuss it in a private, threaded margin conversation.",
+  collection: "documentation",
+  status: "final",
+  order: 17,
+  annotations: "hypothesis",
+)
+
+#let hypothesis = "https://web.hypothes.is"
+
+#let body = [
+  A published result often needs a conversation before it needs another revision. Hypothesis adds
+  that conversation directly to a demolab web page: select a passage, attach a comment, and reply
+  in a shared thread. The annotation stays outside the scientific record, while the experiment,
+  figures, and PDF remain reproducible and unchanged.
+
+  This page is itself an example. Its `meta` block contains `annotations: "hypothesis"`, so the
+  Hypothesis control appears at the right edge of the web edition. Select this sentence and attach
+  a private note to test the complete path.
+
+  == Set up a private reading group
+
+  + Create free Hypothesis accounts for each collaborator.
+  + #link(hypothesis + "/help/how-to-create-a-private-group/")[Create a private group], then send
+    its invitation link to the people who should read and reply.
+  + Open an annotated demolab page, sign in through the sidebar, and select that private group
+    before posting. The public layer is a different destination; check the group name on every
+    new top-level comment when the discussion must remain private.
+
+  Replies form a thread beneath the selected passage. Hypothesis also supports page notes for
+  comments about the whole experiment and LaTeX between double dollar signs for mathematical
+  discussion.
+
+  == Enable annotations
+
+  To annotate every article and experiment, add one field to the root `demolab.yaml`:
+
+  ```yaml
+  annotations: hypothesis
+  ```
+
+  To enable only selected entries, omit the root field and add the provider to a writing's
+  metadata instead:
+
+  ```typ
+  #let meta = (
+    title: "A result to review",
+    date: "2026-08-07",
+    annotations: "hypothesis",
+  )
+  ```
+
+  Entry metadata wins over the lab setting. Set `annotations: none` on one entry to keep it
+  unannotated when the rest of the lab has Hypothesis enabled.
+
+  == What gets published
+
+  The setting adds the hosted Hypothesis client to web entry pages only. It does not add scripts
+  to the homepage, collection listings, standalone PDFs, or the combined book. Comments and group
+  membership live in Hypothesis rather than the git repository, so rebuilding the site does not
+  publish a private discussion or alter a recorded result.
+
+  An annotation targets the page URL and records several descriptions of the selected text. Small
+  layout changes and unrelated edits usually leave it attached. Moving the page to another URL,
+  deleting the selected passage, or substantially rewriting its context can orphan it. Keep entry
+  IDs stable and resolve important review comments before replacing the prose they target.
+
+  == Operational boundary
+
+  This option loads JavaScript from `hypothes.is` and sends annotation content to the Hypothesis
+  service. That is an intentional external dependency, not part of demolab's committed research
+  record. Do not enable it for material whose hosting or data policy forbids that service. Review
+  #link(hypothesis + "/privacy/")[Hypothesis privacy information] with your collaborators before
+  using it for sensitive or unpublished work.
+]

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

@@ -14,6 +14,11 @@ description: A lab notebook for computational science — reproducible results,
 # author: Your Name
 # contact: you@example.com
 
+# 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.
+# annotations: hypothesis
+
 # Optional custom landing page — not a config key: create a `landing.typ` at the repo root
 # exporting `#let body = [...]` and the homepage renders it (web only) instead of the collection
 # directory, below the title/tagline/byline above. Delete the file to get the directory back.

{demolab_cli-2.2.1 → demolab_cli-2.3.0}/demolab_cli/test_engine_build.py

@@ -102,6 +102,30 @@ def test_demo_fixture_builds_full_site(tmp_path: Path) -> None:
     assert '<ul class="coll-list"' in index, "collection directory visible in a user lab"
     entry = (site / "ar018.html").read_text()
     assert "<img" in entry or "<svg" in entry, "a figure made it into the entry page"
+    annotated = (site / "ar027.html").read_text()
+    assert 'src="https://hypothes.is/embed.js"' in annotated, "opted-in entry embeds Hypothesis"
+    assert 'src="https://hypothes.is/embed.js"' not in entry, "annotations remain opt-in"
+
+
+def test_lab_wide_hypothesis_annotations_only_touch_entries(tmp_path: Path) -> None:
+    root = tmp_path / "repo"
+    root.mkdir()
+    _assemble(root, demo=True)
+    with (root / "demolab.yaml").open("a", encoding="utf-8") as config:
+        config.write("\nannotations: hypothesis\n")
+    opted_out = root / "writings" / "ar018.typ"
+    opted_out.write_text(
+        opted_out.read_text(encoding="utf-8").replace("order: 1,", "order: 1,\n  annotations: none,"),
+        encoding="utf-8",
+    )
+    _build(root)
+
+    site = root / "artifacts" / "site"
+    embed = 'src="https://hypothes.is/embed.js"'
+    assert embed in (site / "ar019.html").read_text(), "root config enables normal entries"
+    assert embed not in (site / "ar018.html").read_text(), "entry metadata can opt out"
+    assert embed not in (site / "index.html").read_text(), "homepage remains annotation-free"
+    assert embed not in (site / "documentation.html").read_text(), "listings remain annotation-free"
 
 
 def test_curated_collection_lists_in_reading_order(tmp_path: Path) -> None:

{demolab_cli-2.2.1 → demolab_cli-2.3.0}/demolab_cli/typ/entry.typ

@@ -5,7 +5,8 @@
 #let has-brand = sys.inputs.at("has-brand", default: "false") == "true"
 #let config = if has-brand { yaml("/demolab.yaml") } else { (:) }
 #let brand = default-brand + config
+#let annotations = config.at("annotations", default: none)
 #import "/writings/" + entry-id + ".typ" as writing
 
 #set document(title: writing.meta.title)
-#numbered-pages(entry-page(writing.meta, writing.body, id: entry-id, brand: brand))
+#numbered-pages(entry-page(writing.meta, writing.body, id: entry-id, brand: brand, annotations: annotations))

{demolab_cli-2.2.1 → demolab_cli-2.3.0}/demolab_cli/typ/lib.typ

@@ -31,7 +31,7 @@
 }
 
 // --- web-styles: inject the stylesheet + head meta into HTML pages (ignored in the PDF pass) ---
-#let web-styles(brand: default-brand) = context {
+#let web-styles(brand: default-brand, annotations: none) = context {
   if target() == "html" {
     html.elem("link", attrs: (rel: "icon", type: "image/svg+xml", href: "favicon.svg"))
     html.elem("style", read("/.demolab/style.css"))
@@ -42,6 +42,11 @@
     }
     // hover popovers for inline citations (no-op on pages without cites)
     html.elem("script", attrs: (src: "cite-popover.js", defer: ""))[]
+    // Optional collaborative web annotations. The hosted Hypothesis client owns accounts,
+    // private groups, storage, anchoring, and threads; demolab only opts this page into it.
+    if annotations == "hypothesis" {
+      html.elem("script", attrs: (src: "https://hypothes.is/embed.js", async: ""))[]
+    }
   }
 }
 
@@ -393,8 +398,11 @@
   html.elem("p", attrs: (class: "page-foot"), html.elem("a", attrs: (href: "index.html"), [← back to all entries]))
 }
 
-#let entry-page(meta, body, id: none, brand: default-brand) = {
-  web-styles(brand: brand)
+#let entry-page(meta, body, id: none, brand: default-brand, annotations: none) = {
+  // Entry metadata can override the lab-wide provider. `none` disables a global provider for
+  // one entry; absent metadata inherits the root demolab.yaml setting.
+  let annotation-provider = meta.at("annotations", default: annotations)
+  web-styles(brand: brand, annotations: annotation-provider)
   set text(font: "New Computer Modern", size: 11pt)
   // Restart figure numbering per entry: the whole bundle is one compile, so Typst's global
   // figure counter would otherwise carry across every document. Each entry (its page + its

{demolab_cli-2.2.1 → demolab_cli-2.3.0}/demolab_cli/typ/main.typ

@@ -24,6 +24,7 @@
 // read from it too. Absent ⇒ engine defaults + derivation-only collections.
 #let config = if manifest.has_brand_config { yaml("/demolab.yaml") } else { (:) }
 #let brand = default-brand + config
+#let annotations = config.at("annotations", default: none)
 #let collection-order = config.at("collection-order", default: ())
 #let collection-meta = config.at("collections", default: (:))
 
@@ -79,8 +80,8 @@
   }
 }
 #for e in entries {
-  [#document(e.id + ".html", title: [#e.meta.title])[#entry-page(e.meta, e.body, id: e.id, brand: brand)]]
-  [#document("pdfs/" + e.id + ".pdf", title: [#e.meta.title])[#numbered-pages(entry-page(e.meta, e.body, id: e.id, brand: brand))]]
+  [#document(e.id + ".html", title: [#e.meta.title])[#entry-page(e.meta, e.body, id: e.id, brand: brand, annotations: annotations)]]
+  [#document("pdfs/" + e.id + ".pdf", title: [#e.meta.title])[#numbered-pages(entry-page(e.meta, e.body, id: e.id, brand: brand, annotations: annotations))]]
 }
 // stub pages for entries that failed to build — a visible "this page failed" placeholder at the
 // entry's own URL (web only; excluded from listings + the book), so the rest of the site is fine.

demolab_cli-2.2.1/demolab_cli/VERSION

@@ -1 +0,0 @@
-2.2.1