feat(docs): add doc-model types and helpers

[mikhd]

[1] Add the full public type contract for the generator (DocModel / DocPage / DocRef / DocConfig, etc.) plus the small ref/name helpers everything downstream reuses.

Further folder structure:

  src/docs/
  ├── index.ts              Public barrel - exports
  ├── types.ts              All doc types (DocConfig, DocRef, DocPage, DocModel, PathConfig, etc.)
  ├── generateDocs.ts       Entry point - orchestrates registry -> render -> model
  ├── navigation.ts         buildNavRegistry (path assignment) + categoryGroups
  ├── ref.ts                DocRef name helpers (refName, displayName, pascalCase, docRefKey)
  ├── links.ts              Links for hrefs
  └── render/
      ├── index.ts          Barrel for render layer
      ├── markdown.ts        markdownRenderer for primitives - MarkupRenderer implementation
      ├── renderType.ts      TypeExpr + helpers (linkedEntity, isDocChild, referencesEnumeration)
      ├── constants.ts      consts
      └── renderPages.ts     Per-page-kind renderers + RenderCtx (node/union/nestedUnion/enum/categoryIndex/rootIndex)

High level overview

  generateDocs(spec, config) runs in three passes.

  Spec  +  DocConfig ({ pathConfig, linkStrategy, root?, inject? })
    │
    ▼
  1) Build "path" registry for all entities buildNavRegistry(spec, config.pathConfig) [navigation.ts]
    │   Walks every category -> categoryGroups() -> assigns pathSegments to each DocRef. 
    │
    ▼
     link(from, to) = config.linkStrategy(registry.lookup(from), registry.lookup(to))
     │   Registry + strategy -> concrete href fn.
     │   Assembled into RenderCtx = { markup: markdownRenderer, registry, config, link }
     │
    ▼
  2) Render phase (loop over spec.categories) [render/renderPages.ts]
    │   For each entity -> renderNodePage / renderUnionPage / renderNestedUnionPage
    │   / renderEnumPage + each category index page.
    │
    │   Each renderer:
    │     - builds its own DocRef + linkTo = link(ref, target)
    │     - assembles page parts (heading, paragraph, tables/lists, inject slots)
    │     - types resolved via renderType() -> markdown blocks via ctx.markup (MarkupRenderer)
    │     - inject?.() hook can fill 'afterDescription' / 'end' slots with custom markup
    │     - returns DocPage { ref, pathSegments (from registry), content }
    │
    ▼
  ③ buildNavigation(spec, pathConfig)  [navigation.ts]
    │   NavCategory[] with grouped, alphabetically-sorted page refs.
    │
    ▼
  Output DocModel { pages: DocPage[] }

Design note:

Before current implementation we considered a fully format-agnostic doc model where every page is a tree of Block (heading, prose, code, table, list) and Inline (text, ref, pageLink, type) nodes with no knowledge of Markdown, links, or escaping. Then swappable renderer layer would walk that tree and do rendering to specific format (md,html,etc)

This was rejected due to its unnecessary complexity and since we only need md format.

[mikhd]

• feat(docs): add examples #57
• feat(docs): prepare @codama/spec/docs package, add doc .md files #56
• feat(docs): render all page types and wire generateDocs #55
• feat(docs): add markup primitives render #54
• feat(docs): add nav registry #53
• feat(docs): add doc-model types and helpers #52 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.