IntersectMBO / IntersectMBO/evolution-sdk
experiment: replace @effect/docgen with TypeDoc for clickable cross-referenced module docs
- Vorherrschende Sprache
- TypeScript
- Sterne
- 22
- Forks
- 30
- Ø Merge
- 5 Std. 29 Min.
- Gemergte PRs (30 T.)
- 12
Beschreibung
## Context
The current module reference docs are generated by \`@effect/docgen@0.5.2\` using the \`mikearnaldi/docgen-template\` theme. Output is static MDX with signatures and JSDoc text — no clickable type cross-references, no source links to GitHub.
The goal is Haddock-style behaviour: every type name in a signature is a link that jumps to that type's own documentation page.
## Proposed Experiment
Replace \`@effect/docgen\` with **TypeDoc + \`typedoc-plugin-markdown\`** on an isolated output path so both pipelines can run side-by-side without breaking the existing \`/docs/modules/\` route.
### What TypeDoc gives us
- Clickable cross-references for every type in every signature (uses the TypeScript compiler API to resolve them)
- Source links to GitHub out of the box via \`sourceLinkTemplate\`
- Handles generics, branded types, class methods, and conditional types correctly
- \`typedoc-plugin-markdown\` emits MDX consumable by fumadocs
### Implementation plan
1. Add \`typedoc\`, \`typedoc-plugin-markdown\`, and \`typedoc-plugin-frontmatter\` as dev dependencies in \`packages/evolution\`
2. Add a \`typedoc.json\` config in \`packages/evolution\` pointed at existing \`src/\` — output to a new \`docs-typedoc/\` directory
3. Add a \`generate-typedoc-docs\` script in \`docs/scripts/\` that copies the output into \`docs/content/docs/api/\` (parallel to the existing \`modules/\` path)
4. Wire the new path into fumadocs \`source.config.ts\` under a separate \`/docs/api/\` route
5. Audit the output: verify cross-references resolve, source links point correctly, category grouping is preserved
6. Compare UX against the existing \`/docs/modules/\` output and decide whether to migrate fully or keep both
### Acceptance Criteria
- [ ] TypeDoc generates MDX without errors for all exported symbols in \`packages/evolution/src\`
- [ ] Cross-reference links (e.g. clicking \`Data.Constr\` in a TSchema signature) resolve to the correct page
- [ ] Source links open the correct line in GitHub
- [ ] The new output is accessible at \`/docs/api/\` in the docs site without affecting \`/docs/modules/\`
- [ ] Existing \`@effect/docgen\` pipeline is untouched
## Notes
- This is explicitly experimental — full migration is a separate decision pending the audit
- \`externalPattern\` exclusions for Effect library internals will likely need tuning to avoid polluting the output with Effect framework types
Beitragsleitfaden
Rechercherichtung
Start by reading packages/evolution/src, the existing docs/scripts/ generation flow, and fumadocs source.config.ts. Run the current module-doc pipeline, then evaluate a parallel TypeDoc output under docs-typedoc/ and docs/content/docs/api/. Done means the documented acceptance criteria pass without changing /docs/modules/, followed by the planned UX audit and migration decision.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Bewertung
- Tech-Stack
- typescript
- Bereich
- documentation, tooling
- Issue-Typ
- Feature
- Schwierigkeit
- 5/5
- Geschätzter Aufwand
- Über eine Woche
- Aktivitätsstatus
- Veraltet
- Klarheit
- Klar beschrieben
- Anfängerfreundlichkeit
- 35/100