IntersectMBO / IntersectMBO/evolution-sdk

experiment: replace @effect/docgen with TypeDoc for clickable cross-referenced module docs

Aperta
#157 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
documentation enhancement
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.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.