epythet v2: modernization epic (Sphinx 9, README landing, nested API tree, themes, normalizer, validate + ledger, AI artifacts, fleet migration)

[thorwhalen]

Tracking issue for the epythet v2 modernization. The design rationale, evidence, and the fleet migration plan are in the decision record discussion: #15

Scope (one work package per session)

• WP0 — Safety pin (PR Pin epythet to <0.2 in publish-github-pages action #17): the Pages action installs epythet<0.2 until v2 is validated; pin the wads stub to a tagged action ref
• WP1 — Core v2 (PR epythet v2 core (0.2.0): config SSOT, README landing page, nested API tree, themes, docstring normalizer, agent outputs #19, 0.2.0): [tool.epythet] SSOT config, generated conf.py (thin shim if committed), MyST index.md including the README, recursive API generator (nested TOC), theme registry (furo default, curated seven, OKLCH accent), build-time docstring normalizer, agent outputs (llms.txt + .md twins), compatibility entry points (quickstart, make_docsrc, make_autodocs, make)
• WP1b — Single-document aggregates (.md by default, .pdf opt-in via aggregates = ["md", "pdf"]; no separate epythet aggregate command, every html build produces them): <site>/<package>.md (agents) and <site>/<package>.pdf (humans) at stable URLs, produced by default, linked from the landing page and the "For AI agents" section; epythet aggregate tool
• WP2 — epythet validate levels 0 / 0.5 / 1 and the artifact ledger (YAML rules + fixtures, seed rules) — landed in epythet validate (levels 0, 0.5, 1) and the artifact ledger (WP2) #18
• WP3 — validate levels 2 / 3, repair, migrate-style, sweep
• WP4 — Shipped consumer skills and subagents, "For AI agents" docs section template, README rewrite (gh skill install instructions)
• WP5 — Action v2, fleet validation run on a sample of repos, pilot, default flip
• WP6 — Fleet documentation sweep (one session per repo): artifact repair coupled with coverage, correctness and completeness improvements
• R1 — Research: what makes documentation good for agents and for humans (feeds the docstring-style skill and the sweep procedure)

Back-compat contract to preserve

• epythet quickstart <dir> --ignore ... keeps working and writes HTML to ./docsrc/_build/html/
• epythet.config_parser.parse_config keeps its 5-tuple return
• epythet.tools.docstring_diagnosis.diagnose_doctest_code_blocks and repair_package import paths stay stable (used by wads skills)

Folded-in issues

#13 (conf.py SSOT), #9, #10, #8 (Markdown vs RST), #2 (doctest prompt toggle), #11 (doctest detection), #7 (version and date on the page). The wiki's "Documentation problems ledger" becomes the first ledger entries.

Journal

• 2026-09-10: research complete (doc systems, themes, validation tooling, fleet impact, past decisions); baseline render of dol / i2 measured (127 / 119 docutils warnings, dozens of silent artifacts); decision record posted; awaiting maintainer answers on the 8 questions in the discussion.
• 2026-09-10: maintainer accepted all 8 recommendations; added WP1b (flat .md/.pdf aggregates) and the coverage/correctness coupling for WP6 (see discussion epythet v2 — decision record and fleet migration plan (2026-09) #15 comment). Dispatching WP0, WP1, WP2 and R1 in parallel.

[thorwhalen]

WP0 landed: #17 pins the publish-github-pages action to epythet<0.2, so the fleet stays on 0.1.x until v2 is validated.

[thorwhalen]

WP1 journal (2026-09-10) — seam table before the first commit

Branch v2/core. Spike done in a fresh venv (Sphinx 9.1, myst-parser 5.1, sphinx-autoapi 3.8.1, sphinx-llm 1.0.0): the §4/§5/§7 recipes from the research build a copy of dol end to end. Two facts the spike settled:

• sphinx-autoapi 3.8.1 does emit autodoc-process-docstring (its _mapper.py checks for the event and emits it with options=None), so the normalizer hooks under autoapi. Autosummary has no path-exclude, autoapi has autoapi_ignore. So the default is autoapi; autosummary stays the alternative behind the seam.
• Before the normalizer runs, the artifact scan on dol already drops from 266 to 106 and the flat module list is gone (nested autoapi/dol/... tree). Warnings are 94 vs 91 baseline at this point; the normalizer is what moves that number.

#	Seam (keyword)	v1 default (no new dependency beyond the engine)	Replacement pointed at
1	api_generator	"autoapi" (native ignore, no import, docstring event verified)	"autosummary" — stdlib Sphinx, research §5.1 [verified]
2	theme	"auto" → deterministic pick from the curated pool, registry maps accent/mode per theme	any installed theme name via the same key; [tool.epythet.theme_options] passthrough always wins
3	agent_outputs / aggregates	sphinx-llm twins + llms.txt; <pkg>.md produced from the full-build concatenation (zero extra cost)	<pkg>.pdf — WP1b spike, weasyprint or Playwright print
4	normalizer rules	DEFAULT_RULES: tuple of pure list[str] -> list[str] functions	WP2 ledger rules (epythet/ledger/) marked autofixable
5	config source	load_config(project_dir): pyproject.toml ([project] + [tool.epythet]) wins, setup.cfg fallback	[tool.wads.ci.docs] read by wads' ci_config.py (same keys)

Surface for v1: the existing CLI (cw commands) plus the Python API. NOT seams: the conf.py shim text, the index.md layout, the OKLCH constants (salt is a constant), the link-rel hook, the sphinx-build invocation.

[thorwhalen]

R1 done (2026-09-10): research on documentation content quality for agents and humans — report research_doc_quality.md in the local research dir (46 refs). Governing findings for the sweep and the skills:

• Incorrect documentation hurts agents measurably (about 23 points of task success in a controlled study); missing documentation is neutral. So the sweep must never invent behaviour: examples are added only after executing them and pasting real output; semantics change only after reading code and tests.
• Examples beat prose. For less-common libraries (exactly a private 200-package ecosystem), example code is the docs element that helps agents most. Effort goes to entry points, not padding helpers.
• Presence-based coverage tools are blind to information content; the "lazy docstring" that restates the name is the most common smell (about 28% in a benchmark). Two cheap detectors (trivial-summary and type-restatement) go into validate Level 0.
• Verification tiers: structural checks and "every doctest runs" are gates; LLM semantic checkers (precision about 0.6) only rank a work queue.
• Deprioritise llms.txt as a work item; the flat Markdown aggregate (WP1b) is what actually enters an agent's context, and llms.txt is a free pointer to it.

Crowsnest decisions on R1's open questions: (1) release gates are structural correctness plus doctests only; content quality is queue, not gate. (2) No fleet-wide mandatory __all__; public API = non-underscore names, __all__ honoured where present. (3) No fleet rule on docstring mood; consistency within a module is enough, no mass rewrites for mood.

Deliverables to carry into WP2/WP3/WP4: the 23-item gate/queue checklist, the 6-dimension 0-3 rubric, the three-size completeness rubric, the behaviour-claim policy, the 11-row anti-pattern table, and the division-of-labour table (docstring / module docstring / README / site / AGENTS.md / skill / aggregate).

[thorwhalen]

WP2 journal — 2026-09-10: epythet validate levels 0 / 0.5 / 1 and the ledger, first cut on branch v2/validate

Branch pushed; PR to follow once v2/core (WP1) has merged, per the dispatch brief. 125 tests green locally (the ledger's fixture corpus is 88 of them: every seeded bad specimen fires, no control fires).

What landed on the branch

• epythet validate <project|package_dir|import_name> --level {0,1,2} --format {table,json,jsonl} --fail-on {error,warning,info} plus python -m epythet.validation. Exit codes 0 / 1 / 10 / 11 / 12 / 20 as in the research.
• Level 0: ruff check --select D (JSON) and pydoclint (skipped with a note if not installed; type-hint bookkeeping options off).
• Level 0.5: every docstring's docutils doctree, parsed from the ast (no import of the package), with stub Sphinx roles/directives and napoleon's Google/NumPy pre-processing (--no-napoleon to disable; DR012 only applies with napoleon off).
• Level 1: sphinx-build -b html -W -q -w warnings.txt into a temp dir (no --keep-going), [type]-suffixed warnings classified by the build-warning rules.
• Ledger: 31 rules under epythet/ledger/rules/{rendering,source,build}/DRnnn.yaml, 25 with a sibling annotated .py fixture (# ruleid: / # ok: tags) that is the regression test; build rules carry an example_warning that must classify to themselves. Schema violations, duplicate ids and missing fixtures raise LedgerError (exit 20). Observations are appended as JSONL under ~/.local/share/epythet/ledger/observations.jsonl (override with EPYTHET_DATA_DIR); ledger_occurrences on each finding is the derived count.
• Seams: backend= (SphinxBackend, two methods) and ledger= (bundled + overlay directory). Levels 2/3, repair, migrate-style, sweep untouched (WP3).

Baseline calibration (the dol / i2 source copies from the research baseline; one finding per docstring per rule, so paragraph counts from the HTML scan are not directly comparable). Level 1 reproduces the baseline exactly: 127 warnings for dol, 119 for i2.

rule	title	dol	i2
DR011	single backticks → italics	92	63
DR032	docutils message at parse time	60	56
DR010	unbalanced inline markup (*args)	30	30
DR029	Returns: text one-liner	28	3
DR001	field list leaked into prose	26	25
DR016	unexpected indentation → block quote	26	21
DR014	prose as definition term	20	13
DR008	bullet list glued to prose	18	13
DR002	section header in prose (body not indented)	15	12
DR031	commented-out doctest	12	11
DR003	doctest glued to prose	9	8
DR006	Markdown fence	8	10
DR030	docstring starts with a doctest (#11)	7	11
DR017	param list as definition list	3	0
DR004	Markdown link	0	2
DR009	directive text in prose	0	1
DR013	near-miss section name	1	0
DR018	directive content lost	0	1
DR020	backslash in non-raw docstring	1	1
DR028	field without closing colon	1	1
DR015	docutils warning (build)	121	118
DR034	other Sphinx warning (build)	6	1
level 0	ruff D / pydoclint	1173 / 162	1071 / 70

Timings: level 0 ≈ 0.7 s, level 0.5 ≈ 2.3 s (1383 objects), level 1 ≈ 7 s for dol.

For WP1 / WP4 to note: the fixture modules under epythet/ledger/rules/ are real .py files inside the package; the docs build should ignore epythet/ledger so they are not autodoc'd. epythet v2's default_role = "code" will make DR011 a no-op for v2-built packages (the rule's explanation says so).

[thorwhalen]

WP1 journal (2026-09-10, later) — code complete on v2/core, one correction to the seam table

One-command test (fresh venv, pip install -e ., epythet quickstart <copy-of-dol> --ignore tests/ scrap/ examples/, no per-repo config):

metric	0.1.x baseline	v2
dol Sphinx warnings	91	25
dol artifact scan	266	55
dol doctest blocks rendered	755 (incl. facade duplicates)	734
i2 warnings / artifact scan	93 / 197	7 / 109

Landing page is the README (badges, relative images, GitHub alerts and mermaid verified in the smoke test), nested sidebar, Google sections and RST field lists both rendered, llms.txt + .md twins + <pkg>.md + objects.inv + link relations. dol → furo and i2 → sphinxawesome under theme = "auto".

Correction to seam 1: the default api_generator is autosummary, not autoapi. Measured: autoapi's static parsing drops aliases and functools.partial objects (dol.base lost KvStore/Persister/Reader; dol.signatures 84 of 92 objects; doctest blocks 636 vs 734). autoapi stays behind the seam for packages that cannot be imported in CI; it does emit autodoc-process-docstring (verified in 3.8.1), so the normalizer runs under both. ignore under autosummary is exclude_patterns on the generated stubs.

WP1b: <pkg>.md ships by default (it is the Markdown build's concatenation, renamed; llms-full.txt itself is not published) and is linked from the landing page. <pkg>.pdf is implemented behind aggregates = ["md", "pdf"] via Playwright print-to-PDF (dol.pdf, 1.9 MB, 3.2 s; WeasyPrint fallback; no LaTeX), off by default because it needs a Chromium download. No separate epythet aggregate command: every html build produces the aggregates.

Other decisions: epythet make always runs sphinx-build -E (a stale pickled environment silently dropped the API pages when the generator changed); an empty --ignore means "use the configured default"; myst.xref_missing is suppressed because an included README always links to repo files that are not site pages. Tests: 120 (config precedence incl. the setup.cfg bug, 23 normalizer in/out fixtures + fixed-point check, conf generation, theme registry and accent contrast floor, CLI goldens, and a Sphinx smoke build of a fixture package). Next: adversarial review, then the PR.

[thorwhalen]

WP2 journal — 2026-09-10, after the adversarial review of PR #18: two blockers fixed (prose regexes matched text inside inline literals; ledger fixtures were scanned as package source) plus the should-fixes listed in the PR body. Effect on the baseline counts above: DR032 (docutils message catch-all) drops from 60 / 56 to 2 / 1 on dol / i2 because it now fires only when no specific rule did; DR013 no longer flags a Usage: section; DR011 (single backticks) ships at info so --fail-on warning is usable fleet-wide; i2 gains one DR001 from a def inside an if block that was previously skipped. Everything else is unchanged, level 1 still reproduces the baseline (127 / 119). Dogfooding: epythet validate epythet --level 1 finds 5 real errors in epythet's own pre-existing docstrings (a Returns:-style Example: header in tools/published_docs.py, two glued bullet lists and a \b backslash in __init__.py, a glued list in tools/docstring_diagnosis.py), left for WP1/WP6 since those files are being rewritten.

[thorwhalen]

WP1 + WP1b landed (2026-09-10)

Merged: #19 (squash, 2a68782). This ships epythet 0.2.0 to PyPI on master's CI run. The publish action stays pinned to epythet<0.2 (#17), so no fleet site changes until WP5 flips the pin.

Closed by the PR: #13 (conf.py SSOT), #8, #9, #10 (Markdown habits render, RST keeps rendering).

An independent adversarial review ran before merge (3 high / 6 medium / 9 low findings, all fixed except two documented caveats: autosummary still imports ignored modules once during discovery; projects pinning sphinx<9 conflict with 0.2 in one environment). It also asked for, and got, a page seam for WP4: scaffold(config, pages=[PageSpec(...)]).

WP2 (#18, v2/validate) rebases onto this and lands next.

[thorwhalen]

WP2 landed: #18 squash-merged to master as ca8c634 (after rebasing on #19; fixture corpus and dol/i2 baselines re-run on the v2 layout, counts unchanged). epythet validate and the ledger ship with the next release; #11 closed by DR030. Handoff to WP3 (levels 2/3, repair, migrate-style, sweep): seams are backend= (BuildBackend protocol in epythet/validation/build.py), ledger= (overlay dir; status: {proposed: ...} rules are skipped unless include_proposed), validate(levels=[0.5]) for the sweep, and Finding.strategy carrying each rule's fix.strategy for repair.