agents-docs-sync
agents-docs-syncは、Python で実装された CI/CD パイプラインの補助ツールです。
GitHub Actions 等に組み込むことで、コードをコミットするたびに以下が自動的に行われます。
- テスト実行 –
pytest(pyproject.toml に uv で管理)とカバレッジ計測 (pytest-cov) を使用してすべてのユニット・統合テストを走らせ、失敗時はビルドを中断します。 - ドキュメント生成 –
pyyamlによって YAML で定義されたエージェント構成から Markdown / MkDocs のページを自動作成し、最新の API ドキュメントと設定例を常に同期させます。 - AGENTS.md 自動更新 – プロジェクト内の全てのエージェント定義(
agents/*.py,config/**/*.yamlなど)から情報を抽出し、概要・使用方法・依存関係をまとめたAGENTS.mdを再生成します。 - レポート作成 – テスト結果とカバレッジ統計は GitHub の Actions レポートに添付されるほか、必要に応じて Slack やメールで通知できます。
主なファイル構造
agents-docs-sync/
├─ scripts/ # コマンドラインスクリプト (sync.py, generate_docs.sh)
├─ agents/ # エージェント実装(Python)
├─ config/ # YAML 設定・テンプレート
└─ docs/ # MkDocs / Sphinx 用の静的ファイル生成先
実行方法
# 依存関係をインストール (uv を使用)
uv sync
# 手動で同期実行(CI の代わりにローカルテスト)
uv run scripts/sync.py --all
--all オプションは、全てのステップ(テスト・ドキュメント生成・AGENTS.md 更新)を順次走らせます。
GitHub Actions では actions/setup-python@v5, github/codeql-action/upload-sarif@v1.0.3 等と組み合わせることで、CI パイプラインに簡単に統合できます。
主なメリット
- ドキュメントの整合性維持:コード変更ごとに自動生成されるため、手作業で更新するミスが減ります。
- 品質保証:テスト失敗時は即座にビルドを停止し、デプロイ前に問題点を検出できます。
- 開発者体験向上:
AGENTS.mdにエージェントの概要と使用例が自動でまとめられるため、新規メンバーも迅速に理解できるようになります。
依存関係
# pyproject.toml (uv)
[tool.uv]
dev-dependencies = [
"pyyaml>=6.0.3",
"pytest>=7.4.0",
"pytest-cov>=4.1.0",
"pytest-mock>=3.11.1"
]
これらはすべて uv sync で解決され、CI 環境でも同一バージョンが保証されます。
graph TB
%% Auto-generated architecture diagram
subgraph agents_docs_sync [fa:fa-python agents-docs-sync]
direction TB
subgraph docgen [docgen]
direction TB
docgen_collectors["collectors"]:::moduleStyle
subgraph docgen_utils [utils]
direction TB
docgen_utils_llm["llm"]:::moduleStyle
end
class docgen_utils moduleStyle
subgraph docgen_cli [cli]
direction TB
docgen_cli_commands["commands"]:::moduleStyle
end
class docgen_cli moduleStyle
docgen_models["models"]:::moduleStyle
subgraph docgen_archgen [archgen]
direction TB
docgen_archgen_detectors["detectors"]:::moduleStyle
docgen_archgen_generators["generators"]:::moduleStyle
end
class docgen_archgen moduleStyle
docgen_benchmark["benchmark"]:::moduleStyle
docgen_detectors["detectors"]:::moduleStyle
subgraph docgen_generators [generators]
direction TB
docgen_generators_services["services"]:::moduleStyle
docgen_generators_parsers["parsers"]:::moduleStyle
end
class docgen_generators moduleStyle
docgen_validators["validators"]:::moduleStyle
subgraph docgen_rag [rag]
direction TB
docgen_rag_strategies["strategies"]:::moduleStyle
end
class docgen_rag moduleStyle
docgen_config["config"]:::moduleStyle
end
class docgen moduleStyle
end
docgen_collectors --> docgen_models
docgen_collectors --> docgen_utils
docgen_utils --> docgen_detectors
docgen_utils --> docgen_models
docgen_utils_llm --> docgen_models
docgen_cli --> docgen_archgen
docgen_cli --> docgen_generators
docgen_cli --> docgen_rag
docgen_cli --> docgen_utils
docgen_cli_commands --> docgen_rag
docgen_cli_commands --> docgen_utils
docgen_archgen --> docgen_detectors
docgen_archgen --> docgen_generators
docgen_archgen --> docgen_models
docgen_archgen --> docgen_utils
docgen_archgen_detectors --> docgen_models
docgen_archgen_generators --> docgen_models
docgen_benchmark --> docgen_models
docgen_benchmark --> docgen_utils
docgen_detectors --> docgen_models
docgen_detectors --> docgen_utils
docgen_generators --> docgen_archgen
docgen_generators --> docgen_collectors
docgen_generators --> docgen_detectors
docgen_generators --> docgen_models
docgen_generators --> docgen_utils
docgen_generators_parsers --> docgen_detectors
docgen_generators_parsers --> docgen_models
docgen_generators_parsers --> docgen_utils
docgen_validators --> docgen_detectors
docgen_validators --> docgen_generators
docgen_validators --> docgen_models
docgen_validators --> docgen_utils
docgen_rag --> docgen_utils
docgen_rag_strategies --> docgen_utils
classDef pythonStyle fill:#3776ab,stroke:#ffd43b,stroke-width:2px,color:#fff
classDef dockerStyle fill:#2496ed,stroke:#1d63ed,stroke-width:2px,color:#fff
classDef dbStyle fill:#336791,stroke:#6b9cd6,stroke-width:2px,color:#fff
classDef moduleStyle fill:#f9f9f9,stroke:#333,stroke-width:2px
Services
agents-docs-sync
- Type: python
- Description: コミットするごとにテスト実行・ドキュメント生成・AGENTS.md の自動更新を行うパイプライン
- Dependencies: anthropic, hnswlib, httpx, jinja2, mypy, openai, outlines, pip-licenses, psutil, pydantic, pytest, pytest-cov, pytest-mock, pyyaml, radon, ruff, sentence-transformers, torch, types-pyyaml
使用技術
- Python
- Shell
依存関係
- Python:
pyproject.tomlまたはrequirements.txtを参照
セットアップ
前提条件
- Python 3.12以上
インストール
Python
# uvを使用する場合
uv sync
LLM環境のセットアップ
APIを使用する場合
-
APIキーの取得と設定
- OpenAI APIキーを取得: https://platform.openai.com/api-keys
- 環境変数に設定:
export OPENAI_API_KEY=your-api-key-here
-
API使用時の注意事項
- APIレート制限に注意してください
- コスト管理のために使用量を監視してください
ローカルLLMを使用する場合
-
ローカルLLMのインストール
- Ollamaをインストール: https://ollama.ai/
- モデルをダウンロード:
ollama pull llama3 - サービスを起動:
ollama serve
-
ローカルLLM使用時の注意事項
- モデルが起動していることを確認してください
- ローカルリソース(メモリ、CPU)を監視してください
ビルドおよびテスト
ビルド
uv sync
uv build
uv run python3 docgen/docgen.py
テスト
bash scripts/run_tests.sh
uv run pytest tests/ -v --tb=short
コマンド
プロジェクトで利用可能なスクリプト:
| コマンド | 説明 |
|---|---|
agents_docs_sync |
docgen.docgen:main |
agents-docs-sync |
docgen.docgen:main |
agents_docs_sync のオプション
| オプション | 説明 |
|---|---|
--config |
設定ファイルのパス |
--quiet |
詳細メッセージを抑制 |
--detect-only |
言語検出のみ実行 |
--no-api-doc |
APIドキュメントを生成しない |
--no-readme |
READMEを更新しない |
--build-index |
RAGインデックスをビルド |
--use-rag |
RAGを使用してドキュメント生成 |
--generate-arch |
アーキテクチャ図を生成(Mermaid形式) |
agents-docs-sync のオプション
| オプション | 説明 |
|---|---|
--config |
設定ファイルのパス |
--quiet |
詳細メッセージを抑制 |
--detect-only |
言語検出のみ実行 |
--no-api-doc |
APIドキュメントを生成しない |
--no-readme |
READMEを更新しない |
--build-index |
RAGインデックスをビルド |
--use-rag |
RAGを使用してドキュメント生成 |
--generate-arch |
アーキテクチャ図を生成(Mermaid形式) |
このREADME.mdは自動生成されています。最終更新: 2025-12-24 16:04:17
Metadata
Release files for agents-docs-sync 0.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agents_docs_sync-0.2.1.tar.gz | 384.2 kB | Without provenance | Details for agents_docs_sync-0.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agents_docs_sync-0.2.1-py3-none-any.whl | Python 3 | none | any | Details for agents_docs_sync-0.2.1-py3-none-any.whl |
Total release size: 628.0 kB
Release files / agents_docs_sync-0.2.1.tar.gz
| Download URL | agents_docs_sync-0.2.1.tar.gz |
|---|---|
| Size | 384.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
39c542d3b485f089ec50abe0c51d04ff48d5824ac85dc4d8441183f4d9f7bd77
|
|
BLAKE2b-256 checksum How to use checksums |
1a32488965a83851a45bec073442ae94a8cbc7e3c517ec33a68781b2a6ef1b9e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.4
|
Release files / agents_docs_sync-0.2.1-py3-none-any.whl
| Download URL | agents_docs_sync-0.2.1-py3-none-any.whl |
|---|---|
| Size | 243.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a7689159aadbea35355d237065af3c49703a2c7baad6af58a5247a01a2666810
|
|
BLAKE2b-256 checksum How to use checksums |
dab2e385303c93240fb5bdd00b96adcf19647bba9300e80ef2cbbc450493281d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.4
|
Security for agents-docs-sync 0.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.