IntersectMBO / IntersectMBO/evolution-sdk
experiment: replace @effect/docgen with TypeDoc for clickable cross-referenced module docs
- Lingua principale
- TypeScript
- Stelle
- 22
- Fork
- 30
- Merge medio
- 5h 29m
- PR unite (30g)
- 12
Descrizione
## 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
Guida per i contributori
Apri la guida per i contributori
Valutazione
Questa issue non è ancora stata valutata.