experiment: replace @effect/docgen with TypeDoc for clickable cross-referenced module docs
メンテナーはふだん 1 日以内に返信
まだ誰も着手していません。
評価
- 難易度
- 5/5
- 見積もり時間
- 1週間以上
- 初心者へのやさしさ
- 35/100
- issue の種類
- 機能追加
- 明瞭さ
- 明確に書かれている
- 活発さ
- 停滞
- 技術スタック
- typescript
- 領域
- documentation, tooling
調査の方向性
まず packages/evolution/src、既存の docs/scripts/ の生成フロー、および fumadocs source.config.ts を読みます。次に現在のモジュールドキュメントパイプラインを実行し、その後 docs-typedoc/ と docs/content/docs/api/ における並行した TypeDoc 出力を評価します。/docs/modules/ を変更せずに文書化された受け入れ基準を満たし、その後に計画された UX 監査と移行判断を行えば完了です。
索引モデルが issue の本文から書いたものです。
説明
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
- 主要言語
- TypeScript
- スター
- 22
- フォーク
- 35
- 平均マージ
- 2日 1時間
- マージ済み PR（30日）
- 44
環境構築
- Dockerfile・Docker Compose ファイルなし
- プルリクエストのテンプレートなし
- コントリビューションガイドを読む
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
IntersectMBO/evolution-sdk のほかの issue
-
Kupmios: protocol parameters fail against Ogmios v7 (maxReferenceScriptsSize renamed)対応中かも このイシューにリンクされたプルリクエストがオープン中、またはマージ済みです。 オープンbug
難易度 2/5 1〜3時間 初心者へのやさしさ 84/100
IntersectMBO/evolution-sdk#559 ·
メンテナーはふだん 1 日以内に返信
-
enhancement
難易度 2/5 1〜3時間 初心者へのやさしさ 72/100
IntersectMBO/evolution-sdk#557 ·
メンテナーはふだん 1 日以内に返信
-
dependencies good first issue
難易度 1/5 1時間未満 初心者へのやさしさ 93/100
IntersectMBO/evolution-sdk#541 ·
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 80/100
IntersectMBO/evolution-sdk#518 ·
メンテナーはふだん 1 日以内に返信
-
enhancement external-review
難易度 2/5 1〜3時間 初心者へのやさしさ 84/100
IntersectMBO/evolution-sdk#456 · コメント 1 件 ·
メンテナーはふだん 1 日以内に返信
IntersectMBO/evolution-sdk の issue をすべて見る
似ている issue
-
難易度 2/5 1〜3時間 初心者へのやさしさ 82/100
メンテナーはふだん 1 日以内に返信
-
high priority
難易度 2/5 1〜3時間 初心者へのやさしさ 62/100
CI-CMG/deep-sea-corals-exb#84 · コメント 1 件 ·
-
Create/import wallet form shows raw "password must be at least 1 characters" instead of the translated message対応中かも @CapThunder19 が今日担当しました。 オープンbug
難易度 2/5 1〜3時間 初心者へのやさしさ 82/100
joinmarket-webui/jam#1538 ·
メンテナーはふだん 1 日以内に返信
-
t0ggles
難易度 2/5 1〜3時間 初心者へのやさしさ 70/100
nolimits4web/swiper#8240 · コメント 1 件 ·
-
難易度 2/5 1〜3時間 初心者へのやさしさ 82/100
メンテナーはふだん 1 日以内に返信