shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringNo API key required

sphinx-doc-updater

Automatically updates Sphinx documentation when code changes, API changes, or new features are added. It triggers on changes to public APIs or interfaces, addition of new classes, functions, modules, significant architecture changes, or explicit requests for documentation updates from users. The proposed updates adhere to the MyST format and the project's documentation standards.

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

Sphinx ドキュメント更新スキル

このスキルは、コードベースの変更に応じてSphinxドキュメントを自動的に更新・同期します。

起動条件

以下の状況で自動的に起動します：

  1. API/インターフェース変更: 公開クラス、関数、メソッドのシグネチャが変更された
  2. 新機能追加: 新しいクラス、モジュール、重要な機能が追加された
  3. アーキテクチャ変更: システム設計や構造に影響する変更があった
  4. 明示的な依頼: ユーザーがドキュメント更新を明示的に依頼した
  5. ドキュメントの不整合: コードとドキュメントの内容が乖離している

動作プロセス

1. 変更内容の分析

まず、以下の情報を収集します：

  • 変更されたファイルとその内容
  • 新規追加されたクラス、関数、モジュール
  • 変更されたAPIシグネチャ
  • docstringの内容

2. 影響を受けるドキュメントの特定

プロジェクトのドキュメント構成を分析し、更新が必要なファイルを特定：

  • docs/index.md: クイックスタート、概要
  • docs/architecture.md: アーキテクチャ設計
  • docs/how-it-works.md: 動作原理
  • docs/custom-tools-explained.md: カスタムツールの説明
  • 新規ページの必要性判断

3. ドキュメント更新案の作成

ドキュメント作成ガイドラインは .claude/docs.md を参照してください。

重要なポイント：

  • MyST構文を使用
  • 内部表記を避ける（Phase/Milestone/Article表記等）
  • 保証表現を避ける（「完全サポート」等）
  • 感嘆符を使用しない
  • プロフェッショナルで簡潔な技術文書として記述

4. ユーザーへの確認

更新内容を提示し、以下を確認：

  • 変更の妥当性
  • 追加すべき情報の有無
  • ドキュメント構成の適切性

5. 更新の実行

承認後、以下を実行：

  • ドキュメントファイルの更新
  • 必要に応じて新規ページの作成
  • docs/index.mdのtoctreeへの追加（新規ページの場合）

6. ビルド検証

最後にSphinxビルドでエラーがないことを確認：

uv run sphinx-build -M html docs docs/_build

使用例

例1: 新しいクラスを追加

変更内容:

class ClaudeCodeCLIStreamingModel:
    """ストリーミング対応のClaudeモデル"""

    def __init__(self, model_name: str):
        ...

    async def stream(self, messages: list[dict]) -> AsyncIterator[str]:
        ...

スキルの動作:

  1. docs/architecture.mdにストリーミングモデルのセクションを追加
  2. docs/how-it-works.mdにストリーミングの仕組みを説明
  3. docs/index.mdのクイックスタートにストリーミングの使用例を追加

例2: APIシグネチャの変更

変更内容:

# 変更前
def __init__(self, model_name: str):
    ...

# 変更後
def __init__(self, model_name: str, timeout: int = 30, max_retries: int = 3):
    ...

スキルの動作:

  1. docs/index.mdのクイックスタート例を更新
  2. 新しいパラメータの説明を追加
  3. 既存コード例に新パラメータの使い方を追記（必要に応じて）

例3: アーキテクチャ変更

変更内容:

  • Tool実行の仕組みをリファクタリング
  • 新しいToolExecutorクラスを導入

スキルの動作:

  1. docs/architecture.mdのアーキテクチャ図を更新
  2. 新しいコンポーネントの説明を追加
  3. docs/custom-tools-explained.mdのTool実行フローを更新

ガイドライン参照

重要: 詳細なドキュメント作成ガイドラインは .claude/docs.md を参照してください。

このファイルには以下の情報が含まれています：

  • MyST構文の詳細
  • トーンとスタイルのガイドライン
  • 避けるべき表現（Phase/Milestone/Article表記、保証表現、感嘆符）
  • コードブロックの注意点
  • ビルド検証方法

注意事項

  • 自動実行の制限: このスキルは更新を提案しますが、最終的な実行前に必ずユーザーの確認を求めます
  • ビルドエラー: Sphinxビルドでエラーが発生した場合は、原因を報告し修正案を提示します
  • 既存内容の保持: 既存のドキュメント内容を尊重し、必要最小限の変更を提案します
  • 日本語対応: このプロジェクトのドキュメントは日本語で記述します