gendocs

Overview ¶

Command gendocs regenerates per-service documentation from each service's PARITY.md audit manifest under services/. For every services/<svc> that has a PARITY.md, it writes a friendly services/<svc>/README.md summarizing audit coverage; it also builds a category-grouped service table and injects it into the root README.md between marker comments.

services/qldb and services/qldbsession have no PARITY.md (they're marked REMOVED via hand-written README.md files) and are never touched beyond being listed, as "Removed", in the root table.

Usage:

go run ./cmd/gendocs

Idempotent: running it twice against unchanged PARITY.md files produces no further changes.

Package main implements cmd/gendocs, a documentation generator that reads each service's services/<svc>/PARITY.md audit manifest and emits a friendly services/<svc>/README.md plus a category-grouped service table injected into the root README.md.

The frontmatter in PARITY.md is YAML-shaped but not valid YAML: note: fields are unquoted free text containing commas, colons, and braces inside {...} flow maps, which a real YAML parser chokes on or mis-parses. This file is therefore a deliberately tolerant, line-based parser rather than a yaml.Unmarshal call — see parser_test.go for the specific shapes it was built against. ops:/families: entries are accepted in either YAML form — inline flow maps ("OpName: {wire: ok, ...}") or block mappings ("OpName:" followed by indented "wire:"/... field lines) — since both are ordinary, valid YAML and rejecting one silently undercounts a manifest that is otherwise materially correct (gopherstack-7o96).