2.6 KiB
G-081 punk::args documentation build pipeline (dev doc.* integration)
Status: proposed Scope: src/modules/punk/mix/commandset/doc-999999.0a1.0.tm (doc.* commandset - new generation subcommands), src/scriptapps/tools/punkargs_to_doctools.tcl + punkargs_punknative.tcl (prototypes to productize), src/scriptapps/tools/fontprep/ (shared doc-set asset in link mode), src/doc tree conventions, src/tests coverage Goal: 'dev doc.' generates the external documentation set from punk::args definitions as the source of truth, per package, against the DEV modules (src/modules 999999 versions - not bootsupport snapshots): (a) doctools .man output (Tcl-standard synopsis conventions) validated via dev doc.validate/dtplite and feeding the existing kettle machinery; (b) punk-native html via the G-078 api with a shared punkdoc-mono.woff2 + css (assets link mode, one cached font per doc set) and (c) GFM markdown. Includes the productization items the prototypes deferred: per-form arg tables without repeated panels (prototype has a trim heuristic - production should render per-form tables directly from the spec), deeper-namespace/ensemble command pages (e.g. punk::ansi::ansistring - the prototypes' one-level namespace filter skips them), module/package-level info at page top once G-075 surfaces @package ids, large choice sets as structured lists in markdown, and doctools emitter gaps (@examples -> [example], @seealso/@doc -> [see_also]/[uri], choicelabels). Acceptance: a doc. subcommand generates all three formats for a nominated package list from dev modules in one run; doctools output validates clean (dtplite) and html pages carry the shared font/css by reference; deeper-namespace registered ids appear on the owning package's page (or their own); output tree location and vcs policy decided and documented (generated-vs-committed); at least punk::path + punk::ansi + one ensemble-rich package covered by a regression pin.
Context
Follows the 2026-07-13 assessment (punk::args -> doctools expressibility) and trials: punkargs_to_doctools.tcl (doctools, Tcl-standard by decision - punk s-style is out of scope for that target) and punkargs_punknative.tcl (terminal-faithful html + markdown) both work per-package against bootsupport modules, invoked manually. The doctools comment blocks in source remain interim until this pipeline is validated, after which worthwhile prose migrates into punk::args blocks (original long-term plan). dtplite validation infrastructure (bin/dtplite.cmd + dev doc.validate) is in place. Related: G-075 (@package ids), G-078 (html api), G-079 (default colours), G-014/G-068 (argdoc/moduledoc workflows).