Documentation
¶
Overview ¶
Package docgen renders an instance's analysis reference — the operator catalog, the glossary and the skill pack — as a deterministic Markdown tree (U21). It is NO-EXECUTE: it reads only the instance's InstanceSnapshot (pruned ontology, feature set, extension projection) and the guidance registries in internal/descriptor, and writes through an afero.Fs. It never imports internal/service or internal/processing (TestDocgenImportBoundary).
The tree, paths relative to the export root:
SUMMARY.md mdBook summary fragment listing every page
index.md the landing page
catalog.md the catalog's category index
catalog/<category>.md one page per PurposeSurfaces() category the
instance offers an operator of
reading.md the "Reading your results" index
reading/<family>.md one Interpretation page per result family
(tests, regressions, matrices, overlays,
descriptive) the instance has entries for
reading/components.md the Response.Components floors, weighted
floor keys, mergeability and every visible
operator's ComponentSchema keys
glossary.md every glossary term the instance keeps
skills.md the skill index (omitted with OmitSkills)
skills/<stem>.md every visible skill as the instance serves it
Instance scoping. Every operator, glossary term and skill comes from the instance's PRUNED ontology, so a feature-profiled instance's export carries no page, row, detail block or link for anything it hides. A not-for alternative whose target the prune removed is dropped (the whole list when every alternative is), and every prose string passes through the instance's ProseScrub. Glossary terms are kept or dropped by their owning operators (the same keep-function the virtual glossary skill renders with); a kept term's Forms are its spellings and are rendered verbatim, never token-scrubbed.
Reading pages. Each Interpretation entry renders its Means, its Bands under the named convention, its Sign and its Caveats, scrubbed like every other prose string; a field whose path names a hidden token (p_adjusted without capability:multiplicity) is dropped whole. A shared rule set (the p-value reading) renders ONCE, at the top of the first page citing it — the Test page whenever the instance offers a test — and every citing field links there. Reading pages never link a skill.
Preserved spans. Hand-written prose inside a generated page sits between "<!-- docgen:preserve begin <id> -->" and "<!-- docgen:preserve end <id> -->" lines and is copied verbatim from a file embedded in this package, so regeneration reproduces it byte for byte and an export outside the repository carries it. The Components intro's source of truth is components_intro.md here.
Determinism: every listing is sorted, every map is walked in a fixed order, and Render returns the files sorted by path, so two renders of the same instance are byte-identical.
Index ¶
Constants ¶
const ( BookSpanBegin = "<!-- docgen:summary begin -->" BookSpanEnd = "<!-- docgen:summary end -->" )
BookSpanBegin and BookSpanEnd delimit the generated span of a host book's SUMMARY.md: SpliceSummary replaces every line between them with an export's SUMMARY.md fragment. Both are whole lines; the host book owns everything outside them (the part title included).
Variables ¶
This section is empty.
Functions ¶
func SpliceSummary ¶
SpliceSummary splices fragment — the SUMMARY.md an export writes at its root — into book, the host book's SUMMARY.md, between the BookSpanBegin and BookSpanEnd lines. The fragment's title line and blank lines are dropped and every link path is prefixed with prefix (the export directory relative to the book's src, e.g. "guide/"), so the entries resolve from the book root. The splice is idempotent: splicing the same fragment into its own output returns it unchanged.
It refuses a book without exactly one begin line followed by exactly one end line, and a fragment line that is not a "- [title](path)" list entry.
Types ¶
type File ¶
File is one rendered file of the tree: its slash-separated path relative to the export root, and its bytes.
func Render ¶
func Render(inst *descx.InstanceSnapshot, opts Options) []File
Render renders inst's reference tree. A nil inst renders the unscoped, extension-free instance. The files are sorted by Path. Every file passes through escapePlaceholders, so a bare `<word>` placeholder in prose renders as text rather than as an HTML tag.
Source Files