moai-docs-generation

ドキュメント生成のパターン

クイックリファレンス（30 秒）

目的：確立されたツールとフレームワークを使用して、プロフェッショナルなドキュメントを生成します。

主なドキュメントツール：

• Python：autodoc を備えた Sphinx、Material テーマを備えた MkDocs、pydoc
• TypeScript/JavaScript：TypeDoc、JSDoc、TSDoc
• API ドキュメント：FastAPI/Express の OpenAPI/Swagger、Redoc、Stoplight
• 静的サイト：Nextra（Next.js）、Docusaurus（React）、VitePress（Vue）
• 汎用：Markdown、MDX、reStructuredText

このスキルを使用する場面：

• コードのアノテーションから API ドキュメントを生成する場合
• 検索機能とナビゲーションを備えたドキュメントサイトを構築する場合
• ユーザーガイドや技術仕様書を作成する場合
• CI/CD パイプラインでドキュメントの更新を自動化する場合
• ドキュメント形式を相互に変換する場合

---

実装ガイド（5 分）

Sphinx を使用した Python ドキュメント

Sphinx のセットアップと設定：

pip install sphinx sphinx-autodoc-typehints sphinx-rtd-theme myst-parser を実行して、Sphinx と拡張機能をインストールします。

sphinx-quickstart docs を実行して Sphinx プロジェクトを初期化します。基本的な構成が作成されます。

以下の主な設定を conf.py に記述します：

• extensions に autodoc、napoleon、typehints、myst_parser を含めます
• プロフェッショナルな見た目にするため、html_theme を sphinx_rtd_theme に設定します
• インライン型ヒントを表示するため、autodoc_typehints を description に設定します

ソースディレクトリを指定して sphinx-apidoc を実行し、出力先を docs/api に設定して API ドキュメントを生成します。次に、docs ディレクトリで make html を実行します。

MkDocs を使用した Python ドキュメント

MkDocs Material のセットアップ：

pip install mkdocs mkdocs-material mkdocstrings mkdocstrings-python を実行してインストールします。

mkdocs.yml 設定を作成します：

• site_name と site_url を設定します
• 名前を material に設定し、希望するカラーパレットを指定してテーマを設定します
• search と mkdocstrings などのプラグインを追加します
• セクションとページでナビゲーション構造を定義します

Markdown ファイルで ::: module.path の形式の mkdocstrings 構文を使用すると、docstring から API ドキュメントを自動生成できます。

mkdocs serve でローカル環境に配信し、mkdocs build でビルドして、mkdocs gh-deploy でデプロイします。

TypeDoc を使用した TypeScript ドキュメント

TypeDoc のセットアップ：

npm install typedoc --save-dev を実行してインストールします。

package.json のスクリプトに typedoc --out docs/api src/index.ts を追加します。

typedoc.json で設定します：

• entryPoints にソースファイルを指定します
• out を docs/api に設定します
• includeVersion と categorizeByGroup を有効にします
• theme を default に設定するか、カスタムテーマをインストールします

npm run docs:generate を実行してドキュメントを生成します。

JSDoc を使用した JavaScript ドキュメント

JSDoc のセットアップ：

npm install jsdoc --save-dev を実行してインストールします。

jsdoc.json 設定を作成します：

• ソースの対象パスと includePattern を設定します
• テンプレートと出力先を設定します
• 豊富な書式を利用できるように Markdown プラグインを有効にします

以下のタグを使用して JSDoc コメントで関数を記述します：

• @param：型と説明を含むパラメーター
• @returns：戻り値のドキュメント
• @example：使用例
• @throws：エラーのドキュメント

OpenAPI/Swagger ドキュメント

FastAPI の自動ドキュメント：

FastAPI は OpenAPI ドキュメントを自動生成します。/docs から Swagger UI に、/redoc から ReDoc にアクセスできます。

以下の方法でドキュメントを充実させます：

• ルートハンドラーに docstring を追加します
• 型付きレスポンスには response_model を使用します
• Pydantic モデルの Config クラスで例を定義します
• エンドポイントをグループ化するためにタグを設定します
• ルートデコレーターに詳細な説明を追加します

app.openapi() をプログラムから実行して OpenAPI 仕様をエクスポートし、openapi.json に保存します。

Swagger を使用した Express：

swagger-jsdoc と swagger-ui-express をインストールします。

OpenAPI 定義と API ファイルのパスを指定して swagger-jsdoc を設定します。

ルートハンドラーに @openapi コメントを追加し、パス、パラメーター、レスポンスを記述します。

/api-docs エンドポイントで Swagger UI を配信します。

静的ドキュメントサイト

Nextra（Next.js）：

Nextra の包括的なパターンについては、Skill("moai-library-nextra") を参照してください。

主な利点：MDX のサポート、ファイルシステムルーティング、組み込み検索、テーマのカスタマイズ。

npx create-nextra-app で作成し、theme.config.tsx を設定して、pages ディレクトリ内にページを整理します。

Docusaurus（React）：

npx create-docusaurus@latest my-docs classic で初期化します

docusaurus.config.js で設定します：

• title、tagline、url を指定して siteMetadata を設定します
• docs と blog の設定を含む presets を設定します
• ナビゲーションバーとフッター用の themeConfig を追加します
• algolia プラグインで検索を有効にします

サイドバーの構造には category.json ファイルを使用し、docs フォルダー内にドキュメントを整理します。

VitePress（Vue）：

npm init vitepress で初期化します

.vitepress/config.js で設定します：

• title、description、base path を設定します
• nav と sidebar を含む themeConfig を定義します
• 検索とソーシャルリンクを設定します

Vue コンポーネント、コードハイライト、フロントマターを使って Markdown を記述します。

---

高度なパターン（10 分以上）

SPEC ファイルからのドキュメント生成

MoAI SPEC ファイルからドキュメントを生成するパターン：

SPEC ファイルの内容を読み込み、id、title、description、requirements、api_endpoints などの主要なセクションを抽出します。

構造化された Markdown ドキュメントを生成します：

• description から概要セクションを作成します
• requirements を機能の箇条書きとして列挙します
• 各 API エンドポイントについて、メソッド、パス、説明を記載します
• エンドポイントの定義に基づいて使用例を追加します

生成したドキュメントを docs ディレクトリ内の適切な場所に保存します。

CI/CD ドキュメントパイプライン

GitHub Actions ワークフロー：

src または docs のパスが変更されたときに main ブランチへのプッシュで実行される .github/workflows/docs.yml を作成します。

ワークフローの手順：

• リポジトリをチェックアウトします
• 言語ランタイム（Python、Node.js）をセットアップします
• ドキュメントの依存関係をインストールします
• 適切なツールを使ってドキュメントを生成します
• GitHub Pages、Netlify、または Vercel にデプロイします

Python/Sphinx の例：

• pip install sphinx sphinx-rtd-theme でインストールします
• sphinx-build -b html docs/source docs/build で生成します
• actions-gh-pages アクションを使ってデプロイします

TypeScript/TypeDoc の例：

• npm ci でインストールします
• npm run docs:generate で生成します
• Pages にデプロイします

ドキュメントの検証

リンクチェック：

HTML 出力内のローカルリンクの検証には、linkchecker を使用します。

Markdown には、pre-commit フックで markdown-link-check を使用します。

スペルチェック：

自動スペルチェックには、Aspell とともに pyspelling を使用します。

ファイルの種類ごとに異なるマトリックスエントリーを .pyspelling.yml で設定します。

ドキュメントカバレッジ：

Python では、docstring のカバレッジチェックに interrogate を使用します。

pyproject.toml で最小カバレッジのしきい値を設定します。

カバレッジがしきい値を下回った場合は、CI ビルドを失敗させます。

多言語ドキュメント

Nextra の国際化：

next.config.js で locales 配列と defaultLocale を使って i18n を設定します。

pages/[locale] ディレクトリにロケール別のページを作成します。

翻訳には next-intl などを使用します。

Docusaurus の国際化：

docusaurus.config.js で defaultLocale と locales を使って i18n を設定します。

docusaurus write-translations を使って翻訳ファイルを生成します。

i18n/[locale] のディレクトリ構造に翻訳を整理します。

---

相性の良いもの

スキル：

• moai-library-nextra - Nextra ドキュメントフレームワークの包括的なパターン
• moai-lang-python - Python の docstring 規約と型付け
• moai-lang-typescript - TypeScript/JSDoc のドキュメントパターン
• moai-domain-backend - バックエンドサービスの API ドキュメント
• moai-workflow-project - プロジェクトドキュメントとの統合

エージェント：

• manager-docs - ドキュメントワークフローのオーケストレーション
• expert-backend - API エンドポイントのドキュメント作成
• expert-frontend - コンポーネントのドキュメント作成

コマンド：

• /moai:3-sync - コード変更に伴うドキュメントの同期

---

ツールリファレンス

Python ドキュメント：

• Sphinx：https://www.sphinx-doc.org/
• MkDocs：https://www.mkdocs.org/
• MkDocs Material：https://squidfunk.github.io/mkdocs-material/
• mkdocstrings：https://mkdocstrings.github.io/

JavaScript/TypeScript ドキュメント：

• TypeDoc：https://typedoc.org/
• JSDoc：https://jsdoc.app/
• TSDoc：https://tsdoc.org/

API ドキュメント：

• OpenAPI Specification：https://spec.openapis.org/
• Swagger UI：https://swagger.io/tools/swagger-ui/
• Redoc：https://redocly.github.io/redoc/
• Stoplight：https://stoplight.io/

静的サイトジェネレーター：

• Nextra：https://nextra.site/
• Docusaurus：https://docusaurus.io/
• VitePress：https://vitepress.dev/

スタイルガイド：

• Google Developer Documentation Style Guide：https://developers.google.com/style
• Microsoft Writing Style Guide：https://learn.microsoft.com/style-guide/

---

バージョン：2.0.0 最終更新日：2025-12-30