Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

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

Đang mở
  • Có gì không ổn?
#157 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
35/100
Loại issue
Tính năng
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Đình trệ
Công nghệ
typescript
Lĩnh vực
documentation, tooling

Hướng nghiên cứu

Bắt đầu bằng cách đọc packages/evolution/src, quy trình tạo hiện có trong docs/scripts/ và fumadocs source.config.ts. Chạy pipeline tài liệu module hiện tại, sau đó đánh giá đầu ra TypeDoc song song trong docs-typedoc/ và docs/content/docs/api/. Được xem là hoàn tất khi các tiêu chí nghiệm thu đã được ghi nhận đạt yêu cầu mà không thay đổi /docs/modules/, tiếp theo là đợt kiểm tra UX đã lên kế hoạch và quyết định di chuyển.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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
Ngôn ngữ chính
TypeScript
Star
22
Fork
33
Merge trung bình
2 ngày 1 giờ
Pull request đã merge (30 ngày)
44

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của IntersectMBO/evolution-sdk

Tất cả issue của IntersectMBO/evolution-sdk

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.