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

Offen
  • Stimmt etwas nicht?
#157 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Maintainer antworten meist innerhalb von 1 Tag

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Anfängerfreundlichkeit
35/100
Issue-Typ
Feature
Klarheit
Klar beschrieben
Aktivitätsstatus
Veraltet
Tech-Stack
typescript
Bereich
documentation, tooling

Rechercherichtung

Beginne mit dem Lesen von packages/evolution/src, des bestehenden Generierungsablaufs unter docs/scripts/ und von fumadocs source.config.ts. Führe dann die aktuelle Modul-Dokumentationspipeline aus und evaluiere anschließend eine parallele TypeDoc-Ausgabe unter docs-typedoc/ und docs/content/docs/api/. Als abgeschlossen gilt die Aufgabe, wenn die dokumentierten Abnahmekriterien erfüllt sind, ohne /docs/modules/ zu ändern, gefolgt vom geplanten UX-Audit und der Migrationsentscheidung.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

documentation enhancement

Context

The current module reference docs are generated by `@effect/[email protected]` 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
Vorherrschende Sprache
TypeScript
Sterne
22
Forks
34
Ø Merge
21 Std. 38 Min.
Gemergte PRs (30 T.)
55

Entwicklungsumgebung

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus IntersectMBO/evolution-sdk

Alle Issues in IntersectMBO/evolution-sdk

Ähnliche Issues

Weitere Issues zu TypeScript

Neue Issues direkt in Ihr Postfach

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