configure-docs

/configure:docs

コードドキュメントの標準とジェネレーターを確認し、設定します。

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

次の場合にこのスキルを使用します...	次の場合は別の方法を使用します...
プロジェクトの TSDoc、JSDoc、pydoc、または rustdoc の標準を設定する	関数やモジュールの実際のドキュメント内容を書く
ドキュメントジェネレーター（TypeDoc、MkDocs、Sphinx、rustdoc）を設定する	ドキュメントを GitHub Pages にデプロイする（代わりに /configure:github-pages を使用）
ドキュメントのカバレッジと lint 準拠状況を監査する	生成されたドキュメントの正確性を確認する
CI/CD にドキュメントの適用ルールを追加する	ドキュメント以外のルールについて ruff または biome の設定を編集する（/configure:linting を使用）
ドキュメントの規約を移行する（例：numpy 形式から google 形式へ）	pre-commit フックのみを設定する（代わりに /configure:pre-commit を使用）

コンテキスト

• プロジェクトルート：!pwd
• パッケージファイル：!find . -maxdepth 1 \( -name 'package.json' -o -name 'pyproject.toml' -o -name 'Cargo.toml' \)
• Biome 設定：!find . -maxdepth 1 -name 'biome.json'
• TSDoc 設定：!find . -maxdepth 1 \( -name 'tsdoc.json' -o -name 'typedoc.json' \)
• Python 設定：!find . -maxdepth 1 \( -name 'pyproject.toml' -o -name 'ruff.toml' -o -name '.ruff.toml' \)
• Rust 設定：!find . -maxdepth 1 \( -name 'Cargo.toml' -o -name 'clippy.toml' \)
• Pre-commit：!find . -maxdepth 1 -name '.pre-commit-config.yaml'
• ドキュメントジェネレーター：!find . -maxdepth 1 \( -name 'mkdocs.yml' -o -name 'docusaurus.config.*' \)
• ドキュメントディレクトリ：!find . -maxdepth 1 -type d -name 'docs'

パラメーター

コマンド引数から解析します。

• --check-only：変更せずに準拠状況を報告します（CI/CD モード）
• --fix：確認を求めずに修正を適用します
• --level <minimal|standard|strict>：ドキュメント適用レベル（デフォルト：standard）
• --type <typescript|javascript|python|rust>：言語検出を上書きします
• --generator <typedoc|sphinx|mkdocs|rustdoc>：ドキュメントジェネレーターの検出を上書きします

適用レベル：

• minimal：構文検証のみ（有効なドキュメントコメント）
• standard：公開 API のドキュメントが必須（推奨）
• strict：プライベート項目を含むすべての項目にドキュメントが必要

ジェネレーターの自動検出：

プロジェクトの種類	デフォルトのジェネレーター
TypeScript/JavaScript	TypeDoc
Python	MkDocs（よりシンプル）または Sphinx
Rust	rustdoc
複数言語／その他	MkDocs

実行

このドキュメント標準の設定チェックを実行します。

ステップ 1：プロジェクトの言語を検出する

ファイル構成から言語を特定します。

指標	言語
package.json + tsconfig.json	TypeScript
package.json（tsconfig なし）	JavaScript
pyproject.toml または *.py ファイル	Python
Cargo.toml	Rust

複数言語のプロジェクトでは、検出された各言語を設定します。--type による上書きで、対象を 1 つの言語に絞り込めます。

ステップ 2：現在のドキュメントの状態を分析する

検出された各言語について、既存の設定を確認します。

TypeScript/JavaScript：

• tsdoc.json が存在する（TypeScript）
• Biome で import の整理が設定されている
• ドキュメント生成用に TypeDoc または API Extractor が設定されている

Python：

• pyproject.toml に [tool.ruff.lint.pydocstyle] セクションがある
• 規約（google、numpy、pep257）が指定されている
• ruff の lint select で D ルールが有効になっている

Rust：

• Cargo.toml に [lints.rust] セクションがある
• missing_docs lint が設定されている
• rustdoc 固有の lint 用に [lints.rustdoc] セクションがある

ステップ 3：準拠レポートを生成する

書式付きの準拠レポートを出力します。

Documentation Standards Compliance Report
=========================================
Project: [name]
Languages: [detected languages]
Enforcement Level: [minimal|standard|strict]

Linting Standards:
  TypeScript/JavaScript:
    tsdoc.json              [PASS | MISSING | N/A]
    TypeDoc configured      [PASS | MISSING | OUTDATED]
    API docs generated      [PASS | DISABLED]

  Python:
    ruff pydocstyle        [PASS | MISSING]
    convention             [google | not set]
    D rules enabled        [PASS | DISABLED]

  Rust:
    missing_docs lint      [PASS | DISABLED]
    rustdoc lints          [PASS | PARTIAL]

Documentation Generator:
  Generator type         [typedoc|mkdocs|sphinx|rustdoc]  [DETECTED | SUGGESTED]
  Config file            [config path]                     [EXISTS | MISSING]
  Build script           [command]                         [EXISTS | MISSING]
  Output directory       [docs/|site/|target/doc/]         [EXISTS | NOT BUILT]

Overall: [X issues found]

Next Steps:
  - Run `[build command]` to generate documentation locally
  - Run `/configure:github-pages` to set up deployment

--check-only が指定されている場合は、ここで終了します。

ステップ 4：ドキュメント標準を設定する（--fix が指定された場合、またはユーザーが確認した場合）

検出された言語に基づいて設定を適用します。REFERENCE.md のテンプレートを使用します。

TypeScript の設定

1. スキーマ参照を含む tsdoc.json を作成します
2. TypeDoc をインストールします：npm install --save-dev typedoc
3. エントリーポイントと出力ディレクトリを指定した typedoc.json を作成します

Python の設定

1. [tool.ruff.lint.pydocstyle] セクションを pyproject.toml に追加します
2. 規約を google に設定します（科学分野のプロジェクトでは numpy も使用できます）
3. レベル別のルールを設定します（最小：D1 のみ、標準：規約に応じた D、厳格：すべての D ルール）

Rust の設定

1. [lints.rust] セクションを Cargo.toml に追加します
2. missing_docs = "warn"（標準）または "deny"（厳格）に設定します
3. 壊れたリンクを検出するため、[lints.rustdoc] セクションを追加します

ステップ 5：ドキュメントのテストを設定する

ドキュメントの準拠状況を検証するテストを作成します。

1. TypeScript/JavaScript：typedoc --emit none を実行する docs:check スクリプトを追加します
2. Python：ソースに対して ruff check --select D を実行するテストファイルを追加します
3. Rust：CI に cargo doc --no-deps と cargo clippy -- -W missing_docs を追加します

REFERENCE.md のテストテンプレートを使用してください。

ステップ 6：ドキュメントジェネレーターを設定する

ドキュメントサイトジェネレーターを自動検出するか、設定します。

1. 既存のジェネレーター設定を確認します（見つかった場合は既存のものを使用します）
2. --generator が指定されている場合は、指定されたジェネレーターを使用します
3. それ以外の場合は、検出されたプロジェクトの種類に合わせます
4. 設定ファイルを作成し、ビルドスクリプトを追加します

REFERENCE.md のジェネレーターテンプレートを使用してください。

ステップ 7：pre-commit との連携を追加する

.pre-commit-config.yaml が存在する場合は、検出された言語に対応するドキュメント用フックを追加します。REFERENCE.md のフックテンプレートを使用してください。

ステップ 8：標準の追跡情報を更新する

.project-standards.yaml を更新します。

standards_version: "2025.1"
project_type: "[detected]"
last_configured: "[timestamp]"
components:
  docs: "2025.1"
  docs_level: "[minimal|standard|strict]"
  docs_languages: ["typescript", "python", "rust"]

詳細な設定テンプレートについては、REFERENCE.md を参照してください。

出力

以下を提示します。

1. 言語ごとのステータスを含む準拠レポート
2. 実施した変更（--fix の場合）または提案した変更（対話形式の場合）の一覧
3. ドキュメントテストの実行手順
4. カバレッジを改善するための次のステップ

エージェント向けの最適化

コンテキスト	コマンド
準拠状況をすばやく確認	/configure:docs --check-only
すべての問題を自動修正	/configure:docs --fix
TSDoc の妥当性を確認	`typedoc --emit none 2>&1
Python の docstring を確認	ruff check --select D --output-format=github
Rust の doc lint を確認	`cargo doc --no-deps 2>&1
ドキュメントをビルド（MkDocs）	`mkdocs build --strict 2>&1

関連項目

• /configure:github-pages - GitHub Pages へのデプロイを設定します
• /configure:all - すべての準拠チェックを実行します
• /configure:status - 準拠状況の概要をすばやく確認します
• /configure:pre-commit - pre-commit フックを設定します
• TypeScript/JavaScript 向け biome-tooling スキル
• Python 向け ruff-linting スキル
• Rust 向け rust-development スキル