experiment: replace @effect/docgen with TypeDoc for clickable cross-referenced module docs
Los mantenedores suelen responder en 1 día
Nadie ha tomado este issue todavía.
Evaluación
- Dificultad
- 5/5
- Tiempo estimado
- Más de una semana
- Aptitud para principiantes
- 35/100
- Tipo de issue
- Nueva funcionalidad
- Claridad
- Bien especificado
- Estado de actividad
- Estancado
- Stack tecnológico
- typescript
- Área
- documentation, tooling
Línea de trabajo
Empieza leyendo packages/evolution/src, el flujo de generación existente de docs/scripts/ y fumadocs source.config.ts. Ejecuta la canalización actual de documentación de módulos y, después, evalúa una salida paralela de TypeDoc en docs-typedoc/ y docs/content/docs/api/. Se considera terminado cuando se cumplan los criterios de aceptación documentados sin cambiar /docs/modules/, seguido de la auditoría de UX planificada y la decisión de migración.
Escrito por el modelo de indexación a partir del texto del issue.
Descripción
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
- Add `typedoc`, `typedoc-plugin-markdown`, and `typedoc-plugin-frontmatter` as dev dependencies in `packages/evolution`
- Add a `typedoc.json` config in `packages/evolution` pointed at existing `src/` — output to a new `docs-typedoc/` directory
- Add a `generate-typedoc-docs` script in `docs/scripts/` that copies the output into `docs/content/docs/api/` (parallel to the existing `modules/` path)
- Wire the new path into fumadocs `source.config.ts` under a separate `/docs/api/` route
- Audit the output: verify cross-references resolve, source links point correctly, category grouping is preserved
- 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
- Lenguaje dominante
- TypeScript
- Estrellas
- 22
- Forks
- 33
- Merge medio
- 2 d 1 h
- PR fusionados (30 d)
- 44
Preparar el entorno
- Sin Dockerfile ni archivo de Docker Compose
- Sin plantilla de pull request
- Leer la guía de contribución
Primeros pasos
- Lee el issue completo y luego la guía de contribución del proyecto.
- Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
- Haz un fork del repositorio y trabaja en una rama.
- Abre un pull request que haga referencia al número del issue.
Más de IntersectMBO/evolution-sdk
-
bug
Dificultad 2/5 1-3 horas Aptitud para principiantes 84/100
IntersectMBO/evolution-sdk#559 ·
Los mantenedores suelen responder en 1 día
-
enhancement
Dificultad 2/5 1-3 horas Aptitud para principiantes 72/100
IntersectMBO/evolution-sdk#557 ·
Los mantenedores suelen responder en 1 día
-
dependencies good first issue
Dificultad 1/5 Menos de una hora Aptitud para principiantes 93/100
IntersectMBO/evolution-sdk#541 ·
Los mantenedores suelen responder en 1 día
-
Dificultad 2/5 1-3 horas Aptitud para principiantes 80/100
IntersectMBO/evolution-sdk#518 ·
Los mantenedores suelen responder en 1 día
-
enhancement external-review
Dificultad 2/5 1-3 horas Aptitud para principiantes 84/100
IntersectMBO/evolution-sdk#456 · 1 comentario ·
Los mantenedores suelen responder en 1 día
Todos los issues de IntersectMBO/evolution-sdk
Issues similares
-
submodule-pointer-regression
Dificultad 1/5 Menos de una hora Aptitud para principiantes 72/100
smith-horn/skillsmith#3061 ·
Los mantenedores suelen responder en 1 día
-
area: ops type: test
Dificultad 2/5 1-3 horas Aptitud para principiantes 79/100
accensa/x402-facilitator-stellar#559 ·
Los mantenedores suelen responder en 1 día
-
Fix the no-pin ruling in line-drawings: pin a below-the-record stage at the record's chapterAbiertodocumentation
Dificultad 2/5 1-3 horas Aptitud para principiantes 74/100
cosimochellini/one-piece-zero-spoiler#551 ·
Los mantenedores suelen responder en 1 día
-
getWatched() omits __proto__ directories when cwd is setPosiblemente ocupada @maxazure la tomó hoy. Abierto
Dificultad 2/5 1-3 horas Aptitud para principiantes 79/100
-
area:web enhancement
Dificultad 2/5 1-3 horas Aptitud para principiantes 84/100
Los mantenedores suelen responder en 1 día