rspress-docs-generator

Rspress ドキュメントジェネレーター

通常のプロジェクト作業の一環として、Rspress のドキュメントを作成・保守します。一般的な説明文よりもソースコードに基づくドキュメントを優先し、執筆前にコード、テスト、サンプル、パッケージメタデータ、既存の README を確認してください。

ユースケース

• まだドキュメントサイトがないプロジェクト向けに、新しい Rspress v2 ドキュメントサイトを作成します。
• ユーザー向け機能、API の変更、CLI の変更、または PR に合わせて、既存の Rspress v2 ドキュメントサイトを更新します。
• ドキュメント作業の前に Rspress v1 のバージョンマーカーを検出し、専用の rspress-v2-upgrade スキルに移行作業を引き継ぎます。
• リポジトリのパッケージマネージャーとスクリプトを維持しながら、Rspress ドキュメントを Rslib パッケージまたはワークスペースに統合します。

ワークフロー

1. プロジェクトを調査する

   • パッケージファイル、ソースのエントリーポイント、サンプル、テスト、変更履歴、README ファイルを確認します。
   • Rspress の設定ファイル rspress.config.ts、.js、.mjs、.cjs を検索します。
   • 依存関係から Rspress のバージョンマーカーを確認します。対象は @rspress/core のバージョン、旧式の rspress パッケージまたは rspress/* インポート、@rspress/plugin-* です。
   • ロックファイル（pnpm-lock.yaml、yarn.lock、package-lock.json、bun.lock、bun.lockb）と pnpm-workspace.yaml から、パッケージマネージャーとワークスペースの設定を特定します。
   • 設定ファイルがある場合は、その root オプションからドキュメントのルートを特定します。root がない場合は、パッケージスクリプト、CI コマンド、ドキュメントに記載されたコマンドを調べ、rspress dev site、rspress build site、rspress preview site のような Rspress CLI の位置引数で指定されたルートを確認します。その引数を使用し、該当する引数がなければ、設定ファイルがあるプロジェクトの cwd を基準とする Rspress のデフォルトの docs/ ディレクトリを使用します。設定ファイルがない場合は、docs/、doc/、website/、site/ などの一般的なルートを確認します。

2. 適切な手順を選ぶ

   • Rspress のドキュメントサイトがない場合は、新しいドキュメントの作成に従います。
   • Rspress のドキュメントサイトがあり、v1 の可能性がある場合は、ドキュメントを編集する前にRspress バージョンガードに従います。
   • Rspress v2 のドキュメントサイトがある場合は、PR 向けドキュメントの保守に従います。

3. 完了前に検証する

   • Rspress プロジェクトのディレクトリから、またはリポジトリのルートスクリプトを使って、ドキュメントをビルドします。
   • ビルドの成功を、最優先の成功基準とします。
   • 完了を報告する前に、リンク切れ、ナビゲーション項目の不足、無効なフロントマター、MDX インポートの失敗を修正します。

コード例

ドキュメントの作成や検証には、リポジトリのパッケージマネージャーを使用します。

# Create a new Rspress docs site with the detected package manager.
# Replace pnpm with npm, yarn, or bun when that is the repo package manager.
pnpm create rspress@latest

# Validate from the docs project after replacing starter content.
pnpm run build

PR 向けにドキュメントを保守する場合は、まず変更されたソースを確認してから、該当するドキュメントページとナビゲーションを更新します。

src/formatBytes.ts -> website/docs/api/formatBytes.mdx -> website/docs/api/_meta.json

参考資料

• ドキュメント構造の規約 — _nav.json と _meta.json の仕組みを、Guide/API サイト、グループ化されたセクション、i18n のレイアウトの具体例とともに説明します。
• 新しいドキュメントの作成 — ドキュメントのないプロジェクトに、Rspress v2 のドキュメントサイトを作成します。
• PR 向けドキュメントの保守 — 機能開発に合わせて、既存の Rspress v2 ドキュメントサイトを更新します。
• Rspress バージョンガード — v1 サイトを検出し、古い v1 のひな形の使用を避け、移行全体を rspress-v2-upgrade に引き継ぎます。