IntersectMBO / IntersectMBO/evolution-sdk

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

Offen
#157 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
documentation enhancement
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

Beitragsleitfaden öffnen

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

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.