sphinx-doc-updater

コード変更、API変更、新機能追加時にSphinxドキュメントを自動更新します。公開APIやインターフェースの変更、新クラス・関数・モジュールの追加、アーキテクチャの重要な変更、ユーザーからの明示的なドキュメント更新依頼時に起動します。MyST形式とプロジェクトのドキュメント標準に準拠した更新を提案します。

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

When & Why to Use This Skill

The Sphinx Doc Updater is a specialized Claude skill designed to automatically synchronize technical documentation with codebase changes. It monitors API modifications, new feature additions, and architectural shifts to propose precise updates in MyST format. By integrating directly with the development workflow, it ensures that Sphinx-based documentation remains accurate, professional, and perfectly aligned with the latest source code, significantly reducing the manual overhead of maintaining technical manuals.

Use Cases

  • Automated API Reference Updates: Automatically detect changes in function signatures, class structures, or docstrings and propose corresponding updates to the documentation to prevent stale API info.
  • New Feature Documentation: Generate comprehensive documentation for newly added modules or components, including quick-start guides and usage examples based on the actual code implementation.
  • Architecture Alignment: Update high-level architectural descriptions and system design documents whenever major refactoring or structural changes occur in the project.
  • Documentation Consistency Auditing: Identify and resolve discrepancies between code behavior and existing documentation to ensure developers and users always have reliable information.
  • Sphinx Build Validation: Automatically verify documentation syntax and build integrity using Sphinx commands to ensure that proposed changes don't break the documentation site.
namesphinx-doc-updater
descriptionコード変更、API変更、新機能追加時にSphinxドキュメントを自動更新します。公開APIやインターフェースの変更、新クラス・関数・モジュールの追加、アーキテクチャの重要な変更、ユーザーからの明示的なドキュメント更新依頼時に起動します。MyST形式とプロジェクトのドキュメント標準に準拠した更新を提案します。

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ビルドでエラーが発生した場合は、原因を報告し修正案を提示します
  • 既存内容の保持: 既存のドキュメント内容を尊重し、必要最小限の変更を提案します
  • 日本語対応: このプロジェクトのドキュメントは日本語で記述します