parody 0.1.0__tar.gz

parody-0.1.0/.claude-worktrees/fleet-ember/.devcontainer/devcontainer.json

@@ -0,0 +1,11 @@
+{
+  "name": "parody",
+  "build": { "dockerfile": "../Dockerfile" },
+  "overrideCommand": true,
+  "customizations": {
+    "vscode": {
+      "extensions": ["charliermarsh.ruff", "ms-python.python"]
+    }
+  },
+  "postCreateCommand": "uv sync"
+}

parody-0.1.0/.claude-worktrees/fleet-ember/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+# CI for the parody toolchain itself. (Content repos get their own template
+# via `parody init` in Phase 2.) Golden-parity tests need the private source
+# corpora and auto-skip here; they run locally pre-release.
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync
+      - run: uv run ruff check .
+      - run: uv run parody check --toolchain
+      - run: uv run pytest -q

parody-0.1.0/.claude-worktrees/fleet-ember/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+
+# Build artifacts — never commit build outputs to content or toolchain repos
+# (System B carries 153 MB of versioned PDFs in git; we don't repeat that)
+*.pdf
+.jupytext_cache.json
+.autofig_log.jsonl
+# figure_mover writes media/ relative to cwd (ancestor behavior; parameterize in Phase 2)
+/media/
+
+# OS
+.DS_Store

parody-0.1.0/.claude-worktrees/fleet-ember/CLAUDE.local.md

@@ -0,0 +1,12 @@
+# Resuming task #234
+
+**Task:** Follow the Seed Plan
+
+## Description
+Follow the markdown NEW_PROJECT_SEED_PLAN.md plan developed to stand up this project and absorb the two older systems.
+
+---
+_Manage your context as you work — `project_slug="parody"`, `task_id=234`:_
+- **Briefing** — before you pause/wrap up, `write_task_briefing(…)`: a concise “where things stand / next steps” so the next session resumes cleanly.
+- **Task** — `set_task_next_action`, `edit_task`, `set_task_block`/`clear_task_block`, `complete_task` (or the dashboard’s **Done**).
+- **Project memory** — when you learn something durable & project-wide (a convention, decision, gotcha), `add_project_memory` / `update_project_memory` so every future session across the project inherits it.

parody-0.1.0/.claude-worktrees/fleet-ember/Dockerfile

@@ -0,0 +1,18 @@
+# Parody build environment — the one-command collaboration enabler.
+# pandoc arrives via the pypandoc-binary pin (see parody/toolchain.py),
+# so the image needs no separate pandoc install.
+FROM python:3.12-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+WORKDIR /work
+COPY pyproject.toml uv.lock* README.md ./
+COPY parody ./parody
+RUN uv sync --frozen --no-dev || uv sync --no-dev
+
+ENV PATH="/work/.venv/bin:$PATH"
+ENTRYPOINT ["parody"]

parody-0.1.0/.claude-worktrees/fleet-ember/NEW_PROJECT_SEED_PLAN.md

@@ -0,0 +1,140 @@
+# Parody — Unified Book/Notebook Toolchain (Seed Plan)
+
+**Status:** Approved 2026-06-10; in execution.
+**Name:** `parody` — a play on *parity* (keeping the print and web versions in parity). Confirmed available on PyPI 2026-06-10.
+
+---
+
+## 1. Mission
+
+One authoring toolchain, distributed as an installable Python package with a CLI, that unifies two existing systems by the same author:
+
+- **System A — homepage notebooks pipeline** (private Django monolith `homepage-django`): pandoc-markdown + executed jupytext sources → JSON → imported into Django models, served dynamically at ricopic.one with course-integrated solution gating, exam printing, and per-user annotations.
+- **System B — meta-based book system** (rtc-book et al.): pandoc-markdown + LaTeX → print-quality PDF (MIT Press production) *and* a Jekyll website, machinery shared across books via `meta-*` git submodules synchronized by hard links.
+
+Parody replaces System A's embedded converter scripts and System B's `meta-book`/`meta-common` (and most of `meta-site`). It does **not** replace System A's Django serving layer—that stays in homepage-django and consumes Parody's JSON artifact.
+
+**Ancestor repos (private; reference implementations):**
+- https://github.com/rtc-book/real-time-computing (book), https://github.com/rtc-book/common, https://github.com/rtc-book/site-source
+- https://github.com/ricopicone/meta-book, https://github.com/ricopicone/meta-common, https://github.com/ricopicone/meta-site
+- homepage-django (local): toolchain code listed in §6 inventory.
+
+## 2. Principles (lessons paid for in both ancestors)
+
+1. **Shared machinery is a versioned dependency, never synchronized files.** The meta-* hard-link scheme (`links.json`, `link-here.py`, manual `meta-*-adoption-notes.txt` merges) is the single biggest maintenance failure in System B. Parody is `pip install parody==X.Y.Z`; a book upgrades by bumping a pin.
+2. **The artifact is the contract.** Builds emit machine-readable, schema-versioned JSON (System B already proved this: its LaTeX build emits `book-json/` that generates the website). Consumers (Django importer, static preview, future tools) depend on the schema, not on Parody internals.
+3. **One source, many targets.** Pandoc markdown (with executed-code blocks via jupytext) is the canonical source; targets are JSON artifact, print PDF, standalone HTML preview, (later) slides.
+4. **Content repos are plain.** One repo per book/notebook, no submodules by default. Collaborators clone one repo, run one containerized command, open a PR. Private content (solutions) lives in the private content repo, extracted into the artifact at build, access-controlled at serve time.
+5. **CI exists.** System B has none; every contribution burdens the author's laptop. Content repos build on PR and release artifacts on tag.
+6. **Port incrementally, gated by golden tests.** Never rewrite both pipelines at once. Parity with System A first (it has a live production consumer), System B's print machinery second.
+
+## 3. Architecture
+
+```
+parody (this repo, pip package + CLI)
+├── parody/readers/        markdown + YAML frontmatter; jupytext execution (cached)
+├── parody/filters/        pandoc lua/panflute filters (ported from both ancestors)
+├── parody/writers/
+│   ├── artifact.py       → <slug>.json  (schema below; primary target)
+│   ├── latex.py          → print PDF via latexmk/lualatex profiles   (Phase 3)
+│   └── preview.py        → standalone static HTML for local review   (Phase 2)
+├── parody/cli.py          parody init | build | watch | preview | check
+├── profiles/             LaTeX classes/styles (from rtc styles-tex), HTML templates
+└── tests/golden/         golden artifacts from both ancestors
+
+content repo (one per book/notebook, from `parody init`)
+├── parody.yaml            title, slug, authors, targets, parody version pin
+├── chapters/<ch>/<sec>.md   (+ optional <sec>.py jupytext sources)
+├── assets/               figures etc. (manifest-listed in the artifact)
+├── solutions visibility  via the same .exercise/.exercise-solution divs as System A
+└── .github/workflows/    build on PR; artifact + PDF on tag
+```
+
+### The artifact contract (schema v1)
+
+Superset of homepage-django's current `notebooks_data/*.json` (so the existing Django importer keeps working with minimal change):
+
+```jsonc
+{
+  "schema_version": 1,
+  "generator": "parody X.Y.Z",
+  "source_repo": "github.com/…", "source_commit": "…", "built_at": "…",
+  "title": "…", "slug": "…", "description": "…", "acronym": "…",
+  "author": ["Full Name", "…"],
+  "cover_image": "…", "pdf_file": "…",
+  "assets": [{"path": "assets/fig1.png", "sha256": "…"}],
+  "chapters": [{
+    "slug": "…", "title": "…",
+    "sections": [{
+      "slug": "…", "title": "…",
+      "html": "<rendered html>",
+      "anchors": [{"id": "fig:…", "type": "figure", "title": "…"}],
+      "has_solutions": true,
+      "solutions": {"exe:id": {"content": "<html>", "title": "…"}},
+      "problems":  {"exe:id": "<html>"}
+    }]
+  }]
+}
+```
+
+**Important quirk (verified in System A, Phase 0 of its split plan):** the `html` field is *Django-template-flavored*—System A's `filter.lua` emits `{% media 'path' %}`, `{% static 'path' %}`, and `{% cite 'key' %}` tags that homepage-django re-renders through its template engine at view time (resolving to local `/media/` or S3 URLs, and to its zotero-backed bibliography). Schema v1 keeps this verbatim for parity; Parody's standalone `preview` writer must implement its own resolution of these tags (media → relative asset paths from the manifest; cite → citeproc). Schema v2 should consider neutral asset URLs + manifest instead of embedded tags.
+
+v2 (post-migration, not now): rtc-style stable short-hash IDs per section/anchor (System B uses 2–4-char hashes as directory names, permalinks, cross-ref keys, and print QR targets—its best idea), print page-number map (from the LaTeX build, System B's `book-0-raw.json` trick), neutral asset references replacing embedded Django tags.
+
+## 4. Phases
+
+### Phase 0 — Bootstrap & decisions
+- [x] Confirm name; reserve PyPI; repo + `pyproject.toml` (Python ≥3.11), `uv`/venv, ruff, pytest. *(2026-06-10: name `parody` confirmed available; PyPI reservation pending first publish)*
+- [x] Pin toolchain versions explicitly: pandoc (both ancestors have been bitten by pandoc API churn—System B's adoption notes literally say "might break our build system because the figure environment changed"), pandoc-crossref, jupytext, nbconvert. Provide a Dockerfile/devcontainer from day one (System B's `camerondevine/rtc_docker` proved this is the collaboration enabler). *(pandoc pinned via `pypandoc-binary==1.15` → bundled pandoc 3.6.1, the version the goldens were built with; `parody check --toolchain` verifies; pandoc-crossref deferred to Phase 3 where it first appears)*
+- [x] Decide filter strategy (recommendation: **keep lua filters initially**—System A's `filter.lua` and System B's 2,803-line `filter.lua` are both pandoc-lua; port them as-is per environment, refactor to shared code later. A panflute rewrite is a separate, optional project; do not block migration on it). *(decided: lua kept as-is)*
+
+### Phase 1 — Parity with System A (gates homepage migration)
+- [x] Port verbatim from homepage-django: `convert_notebook_md_to_json.py` (614 LOC), `jupytext_converter_api.py` (1,034), `jupytext_converter_with_execution.py` (471), `filter.lua`, `notebook_helpers.py`/`notebook_utils.py`. Strip Django imports (there are none of substance—these are scripts). *(2026-06-10: only changes—package imports, `media_root` parameterized away from Django root, generator string)*
+- [x] Golden tests: build homepage's 5 notebooks (engineering-artificial-intelligence, general-topics, heat-transfer-lab-manual, mechatronics-lab-manual, sample-notebook) and diff against their committed `notebooks_data/*.json` (normalize: key order, whitespace). Target: semantic identity. *(all 5 pass; normalization = provenance keys only—generator, built_at, source_commit, schema_version—since older goldens predate them)*
+- [x] Add schema_version/provenance keys; `parody check` validates an artifact against the schema. *(schema at `parody/schemas/artifact-v1.json`)*
+- [ ] Release v0.1.0 → homepage-django Phase 2 (see its `NOTEBOOKS_SPLIT_PLAN.md`) swaps its management commands to thin wrappers over this CLI.
+
+### Phase 2 — Content-repo ergonomics
+- [ ] `parody init` scaffold (layout above), `parody build` (JSON + preview), `parody watch` (replaces homepage's `watch_notebooks.py`/livereload), `parody preview` (static HTML so a collaborator never needs Django to see their work).
+- [ ] CI workflow template: build on PR (the missing System B affordance), artifact + checksums on tag.
+- [ ] Migrate homepage notebooks into content repos one at a time, smallest first (sequencing and delivery mechanics are owned by homepage's plan, not this repo).
+
+### Phase 3 — Print target (System B's machinery, ported properly)
+- [ ] Inventory `rtc-book/common/filter.lua` capabilities → port per-environment with golden LaTeX-snippet tests: numbered divs (`.exercise` w/ XSIM, `.example`, `.theorem`/`.lemma`/`.corollary`, `.definition`, `.infobox`, `.listing`, `.algorithm`), semantic spans (`.keyword`, `.index`, `.path`, `.keys`, `.menu`, `.plaincite`), `pandoc-crossref` integration, hashref cross-links.
+- [ ] latexmk profiles from `meta-book` (`latexmkrc_main`, `latexmkrc_solutions`; lualatex, `-shell-escape`/minted; conditional flags `\issolution`, `\ispartial`, `\nocropmarks`); styles from `common/styles-tex` (note: MIT Press class + licensed fonts are **book-private**—they belong in the book's content repo or a private profile package, not in Parody).
+- [ ] Bibliography: single `book.bib` per content repo; citeproc for HTML, biblatex for print (both ancestors already agree on this split).
+- [ ] Targets: full PDF, per-section PDF (System B's `make section h=…`), solutions manual. Sample/marketing pipeline (pdftk watermark, bookmark splitting) ports only if still wanted.
+
+### Phase 4 — Migrate a System B book
+- [ ] Pilot with the smallest/least in-flight meta-based project; `real-time-computing` (MIT Press production constraints, hardware versioning) goes **last**.
+- [ ] Mapping: `meta-book` → Parody latex profiles + CLI; `meta-common` → Parody filters/styles/figure templates; `common/` content → the book's content repo (versioned prose merges in; the separate `common` repo dissolves unless two books truly share prose); `meta-site` + `site-source` → **retire per book** in favor of either (a) the Parody artifact imported into homepage-django (books become first-class citizens of the notebooks UI—likely the point of this whole effort) or (b) `parody preview` static output where a standalone book site must persist (rtcbook.org).
+- [ ] Hardware versioning (`versions.json` → inheritance flattening → conditional prose + parts lists): port **only when the migrating book needs it**, as a Parody plugin/filter, not core.
+- [ ] Adopt short-hash stable IDs into schema v2 here, where the rtc content already carries them.
+
+### Phase 5 — Collaboration hardening
+- [ ] Devcontainer + one-command build documented for outside collaborators; CONTRIBUTING template in `parody init`.
+- [ ] Private-solutions pattern documented: private content repo → artifact carries solutions → serve-time gating (homepage) or excluded preview builds (`parody build --no-solutions`) for public artifacts.
+- [ ] Artifact signing/checksums in the release workflow (homepage's deploy verifies before import).
+
+## 5. Decisions to make early (with recommendations)
+
+| Decision | Recommendation |
+|---|---|
+| Name | **decided:** `parody` (play on parity); PyPI availability confirmed 2026-06-10 |
+| Lua filters vs panflute rewrite | keep lua now; converge later |
+| One Parody repo vs core+profiles split | one repo until a second book needs a private profile (MIT Press styles force a private `parody-profiles-rtc` eventually) |
+| Where does `common`'s shared-prose idea go | dissolve into per-book repos; resurrect as a shared content repo only if two books actually share sections again |
+| Jekyll site replacement | don't rebuild it; homepage Django serves artifacts, `parody preview` covers standalone needs |
+| Execution backend for code cells | keep System A's cached jupytext/nbconvert approach (it works and is already API-cached) |
+
+## 6. Inventory of source material
+
+**From homepage-django** (`teaching/scripts/`, `teaching/utils/`, `scripts/`): converter trio + filter.lua + helpers + watchers (≈2,800 LOC Python, 1 lua filter). Golden outputs: `teaching/notebooks_data/*.json` (5 files). Source corpora to migrate: `teaching/notebooks-source/*` (54 MB, 4 real notebooks + sample).
+
+**From rtc-book/meta**: `common/filter.lua` (2,803 lines), `common/common.mk` (pandoc invocations: `include-files.lua`, `include-code-files.lua`, `section-divs.lua`, `pandoc-crossref`, citeproc/biblatex split), `common/styles-tex/` (`NewMath_MIT.cls`, `environments.sty`—note `environments.sty` also emits the build JSON), `meta-book` (Makefile, latexmkrc profiles, `scripts/`: `build-alone.py`, `split_pdf_at_bookmarks.sh`, hash tooling `new-version*-text.py`, `find_duplicate_hashes.py`), `meta-site` (generate-pages/faux-sources/menus scripts—reference only), `common/versions.json` + `versions-inheriter.py`/`versions-lister.py` (Phase 4, plugin), Docker image recipe.
+
+**Known gotchas inherited:** pandoc version sensitivity; LaTeX-emitted JSON is malformed by construction (System B's `json-clean.py`)—Parody's artifact must come from the pandoc/Python side, never from LaTeX, with the LaTeX build contributing only optional enrichment (page numbers) post-cleaned; duplicate-hash detection must be a build **error**, not a warning; don't commit build artifacts to content repos (System B carries 153 MB of versioned PDFs in git)—releases/object storage instead.
+
+## 7. Definition of done
+
+Parody v1.0 = homepage-django builds nothing locally (all notebook content arrives as pinned artifacts from content repos), at least one former meta-based book builds print PDF + artifact from a plain content repo with CI, and `meta-book`/`meta-common` are archived.

parody-0.1.0/.claude-worktrees/fleet-ember/README.md

@@ -0,0 +1,33 @@
+# parody
+
+*A play on **parity**: keeping the print and web versions of a work in parity.*
+
+One authoring toolchain for books and course notebooks: pandoc markdown
+(with executed jupytext code cells) in, multiple targets out —
+
+- **JSON artifact** (schema-versioned; the contract consumed by
+  [ricopic.one](https://ricopic.one)'s Django importer and other tools)
+- **standalone HTML preview** (planned, Phase 2)
+- **print-quality PDF** via LaTeX profiles (planned, Phase 3)
+
+Parody unifies and replaces the toolchains of two ancestor systems: the
+homepage-django notebooks pipeline and the rtc-book `meta-*` book machinery.
+See [NEW_PROJECT_SEED_PLAN.md](NEW_PROJECT_SEED_PLAN.md) for the full plan.
+
+## Install / develop
+
+Requires Python ≥ 3.11 and [pandoc](https://pandoc.org) (pinned version in
+`parody/toolchain.py`), or use the Dockerfile/devcontainer.
+
+```sh
+uv sync          # create venv + install
+uv run parody --help
+uv run pytest    # golden tests need the ancestor corpora; see tests/golden/
+```
+
+## CLI
+
+```
+parody build <notebook_dir> <output.json>   # build the JSON artifact
+parody check <artifact.json>                # validate artifact against schema
+```