Introducing docgen — narrated demos from Markdown to Manim

Long-form demos should explain how a system works. Narrated diagram videos age well when the script and the visuals are first-class artifacts you can regenerate in CI — not one-off recordings that rot with every UI tweak.

docgen (documentation-generator) is a reusable Python library and CLI for that job: Markdown narration, OpenAI TTS, Whisper-aligned timing, Manim scenes, ffmpeg composition, and validation you can run before you ship. Install it, point it at a docgen.yaml, and build demos from the shell — no IDE plugin required.

Library, not app: pip-installable CLI + YAML + shell/CI.

What it is

docgen ships the video stack you need for scripted explainers:

• TTS narration — Markdown scripts → MP3 via OpenAI (gpt-4o-mini-tts)
• Whisper-style timestamps — word-level timing so visuals can wait on real speech
• Manim animations — the primary visual surface for diagram-heavy segments
• ffmpeg compose / concat — mux audio + video, stitch segments, freeze-tail guard
• validate — A/V drift, freeze ratio, narration lint, Manim layout hints, pre-push checks
• pages — static preview HTML for demo assets
• wizard — optional local web UI to bootstrap narration from project docs

North-star constraints matter as much as features: stable CLI contracts, hybrid config (deterministic merges plus optional OpenAI where it helps), and a hard rule that generated assets come from the tool — not hand-edited “fixes” that paper over generator gaps.

Typical path: narration → TTS → timestamps → Manim → compose → validate.

cd your-project/docs/demos
docgen yaml-generate          # merge hints/defaults into docgen.yaml
docgen narration-generate …   # optional LLM narration from hints
docgen scene-spec-generate …  # declarative Manim YAML
docgen generate-all           # TTS → timestamps → Manim → compose → validate
docgen validate --pre-push

What we shipped recently

1. Declarative Manim: scene-spec-generate + scene-compile

Instead of hand-editing generated Manim classes, maintainers steer with hints and declarative *.scene.yaml specs. OpenAI can emit the YAML; the engine compiles it into _TimedScene classes inside marked regions of scenes.py.

YAML in, timed Manim scenes out — with layout budgets and Whisper wait_word alignment.

The compiler is opinionated in useful ways: rows auto-paginate when they exceed the frame stack budget, oversized specs are rejected, and (when timing.json has Whisper words) each row’s first label can map to a wait_word index so boxes appear with the narration.

docgen scene-spec-generate --segment 01 --compile
docgen scene-compile animations/specs/01-overview.scene.yaml
docgen manim --scene YourGeneratedScene

2. Hints + yaml-generate as the maintainer surface

Demo bundles (typically docs/demos/) prefer hint files with YAML front matter over ad-hoc surgery on merged docgen.yaml. docgen yaml-generate merges segment lists, visual_map, and paths; narration-generate and scene-spec-generate read those hints. Generated narration, scenes, audio, and recordings stay tool-owned so Git review stays honest.

3. Handbook diagrams + Pages-friendly demos

The repo also ships a suite handbook under docs/suite/ (PlantUML sources with Graphviz/CI rendering) and Manim-oriented demo media for GitHub Pages — so architecture stories can ship as diagrams and narrated segments, not only as markdown.

Try it

1. Install from source or git: see jmjava/documentation-generator
2. docgen init a demos bundle (or adopt an existing docs/demos/)
3. Author hints → yaml-generate → narration / scene specs → generate-all
4. Run docgen validate --pre-push before you ship media

If you want demos that explain architecture with speech and diagrams — and you want a pipeline you can re-run instead of re-record — start with a Manim segment and let docgen own the rest.

— John · github.com/jmjava/documentation-generator