Docs for 0.4.0: audit of README, CONFORMANCE, PUBLISHING, docstrings, CLI help

[dvejsada]

This is a full documentation audit of the 0.4.0 release candidate. There are no code changes beyond docstrings and the CLI's help text.

How it was checked

A runner (kept outside the repo) does the following:

• Runs every Python block in the README and CONFORMANCE.md, plus the module docstring examples, against the package, with deprecation warnings treated as errors. Where an example shows a value, the runner checks it.
• Runs every legaldown … shell line, and diffs the README's sample output against the real output.
• Checks that every in-page #anchor link resolves.
• Checks that every name in the public __all__ lists (legaldown, .validator, .grammar, .syntax) is documented, and that every backticked API name resolves.

Before the fixes it found 28 problems; after them, 0.

Fixed

README

• Sample output: the quick start and JSON examples showed lines 14 and 22 for findings that are on line 24, and only one of the two diagnostics.
• Scope section: it said no file is read beyond the document. 0.4.0 reads amended originals, attachment files, and the files beside a template.
• Deprecation note: it now also lists the deprecated importer type aliases. The __all__ trim is labelled "Changed in 0.4.0".
• Signatures: slugify_identifier(value, …), and depth= is keyword-only on the quote readers.
• Public names that were documented nowhere are now documented: SectionIndexEntry, ListItem, Amends, Representative, CustomField, AssemblyResult, AssemblyError. The Form.as_dict() field list is complete.
• Small fixes: "bar seven" → eight skipped rules, the "below" → "above" cross-reference, and a stale mention of assemble.

CONFORMANCE.md

• 85 of 113 rules are implemented, not 84: raw-html was never counted.
• The harness counts are now 234 passed and 39 skipped; the write-back tests had never been counted.
• The answer rules now point at Template.form, not the deprecated assemble. A self-contradicting sentence in the Assembly section is fixed.

.github/PUBLISHING.md

• It no longer says the project "does not exist on PyPI yet". It has been there since 0.1.0.

Docstrings

• quote_blocks no longer refers to the internal quote_content.
• HeadingSpan names {when=...}, not a non-existent {if:} marker.
• AssemblyResult and Question.from_text no longer refer to the deprecated assemble.
• The legaldown and legaldown.validator module docstrings now say what each module holds.

CLI help

• validate now states its output streams and exit statuses.
• assemble states that a template with errors in the template rules is refused.
• The -i and --save-answers help texts are now precise.
• The module usage examples include -i and questions.

pyproject.toml: the description now mentions template assembly.

Verification

• 3169 tests pass with the spec fixtures corpus. ruff is clean.

🤖 Generated with Claude Code

https://claude.ai/code/session_013WmBAc5T7UCKVdpUmg9qxz

---

Generated by Claude Code