Auto Document Generator

自动从代码生成技术文档，支持 Python/JavaScript/Bash，AI 增强文档质量

Security Scan

The skill's files and instructions are coherent with its purpose (auto-generating docs and optionally using AI); no clear misdirection or hidden endpoints were found, but enabling cloud AI will transmit source code to a remote provider and installing third-party packages has usual supply-chain risks.

Purpose & Capability

Name/description match the code and runtime instructions: the package contains parsers, extractors, a generator, templates, a watcher, and an AI enhancer — all expected for an auto-documentation tool. Declared dependencies in SKILL.md (tree-sitter, jinja2, watchdog, optional ollama/openai) align with functionality.

Instruction Scope

SKILL.md and the CLI only instruct parsing local code, generating documentation, and optional AI-enhancement. The AI enhancer will include source code and docstrings in prompts sent to the configured model. That behavior is expected for an AI-enhanced doc tool but means your project code may be transmitted to external services if you choose a cloud provider. There are no instructions that read or transmit unrelated system files or secrets.

Install Mechanism

There is no special install spec in the registry (instruction-only), but the package includes setup.py and requirements.txt so typical installation uses pip. No downloads from untrusted URLs or archive extraction steps were found in the provided files. Installing with pip from an unknown source still carries normal supply-chain risk.

Credentials

The skill declares no required environment variables, which is consistent with optional/local AI usage. However, if you configure cloud AI (OpenAI/Claude) the code will attempt to use the openai library and will thus rely on the usual OpenAI API key environment variables (not explicitly declared). That means enabling cloud AI can expose your code to an external provider — a proportional but privacy-relevant capability.

Persistence & Privilege

The skill does not request always:true, does not claim to modify other skills, and has no mechanism for forced global persistence. It runs as a normal installable tool and CLI; no elevated privileges or hidden background persistence were observed in the provided code.

Assessment

This package appears to do what it claims: parse code and generate docs, optionally using AI. Before installing, consider: 1) If you enable AI enhancement with a cloud provider, your source code and docstrings will be sent in prompts to that provider — use a local model (ollama) if you need to keep code on-premise. 2) Review requirements.txt / setup.py and run the install in an isolated environment (virtualenv/container) to limit supply-chain risk. 3) If you rely on tree‑sitter language bindings, those native packages may require builds; check they come from trustworthy sources. 4) If you plan to use Git hooks/CI integration, inspect the exact hook scripts the tool will install. 5) If you want higher assurance, run the tool on non-sensitive code first and/or audit the full repository (the scan here truncated some files).

Auto Document Generator - 自动文档生成器

版本: v1.0.0
创建者: 思捷娅科技 (SJYKJ)
更新时间: 2026-03-16
用途: 自动从代码生成技术文档，保持文档与代码同步

---

🎯 核心功能

1. 代码注释提取

• ✅ 多语言支持: Python, JavaScript, Bash
• ✅ 多种注释风格: Google, Numpy, Sphinx, JSDoc
• ✅ 智能提取: 自动识别参数、返回值、异常
• ✅ 类型推断: 从代码中推断类型信息

2. 文档生成

• ✅ API 文档: 自动生成 API 参考文档
• ✅ README 生成: 根据项目信息生成 README
• ✅ 多格式输出: Markdown, HTML, PDF（可选）
• ✅ 模板系统: Jinja2 模板，支持自定义

3. AI 增强（可选）

• ✅ 描述增强: AI 改进函数/类描述
• ✅ 示例生成: 自动生成代码示例
• ✅ 可读性改进: 优化文档结构
• ✅ 参数说明补充: 自动补充缺失的参数说明

4. 自动更新

• ✅ 文件监听: 实时监听代码变更
• ✅ Git Hooks: 提交前自动更新文档
• ✅ CI/CD 集成: GitHub Actions 自动化

---

🚀 快速开始

安装

# 从 ClawHub 安装
clawhub install auto-document-generator

# 或从源码安装
git clone https://github.com/zhaog100/openclaw-skills
cd openclaw-skills/skills/auto-document-generator
pip install -e .

基础用法

# 生成 API 文档
auto-doc-generator generate --input src/ --output docs/

# 启用 AI 增强
auto-doc-generator generate --input src/ --ai --model llama3

# 生成 HTML 格式
auto-doc-generator generate --input src/ --format html

# 监听文件变更
auto-doc-generator watch --input src/ --output docs/

# 初始化项目配置
auto-doc-generator init --project myproject

---

📖 使用示例

1. 生成 API 文档

from auto_doc_generator import CodeParser, CommentExtractor, DocumentGenerator
from auto_doc_generator.parser import Language

# 解析代码
parser = CodeParser(Language.PYTHON)
result = parser.parse_file("src/my_module.py")

# 提取注释
extractor = CommentExtractor()
for func in result.functions:
    func.parsed_doc = extractor.parse_docstring(func.docstring)

# 生成文档
generator = DocumentGenerator()
doc_content = generator.generate_api_doc([result])

# 保存文档
generator.save_documentation(doc_content, "docs/API.md")

2. AI 增强文档

from auto_doc_generator import CodeParser, AIEnhancer, AIConfig

# 配置 AI
ai_config = AIConfig(
    provider="ollama",
    model="llama3",
    local=True
)

enhancer = AIEnhancer(ai_config)

# 增强描述
enhanced_desc = enhancer.enhance_description(
    code=func.source_code,
    existing_doc=func.docstring
)

# 生成示例
examples = enhancer.generate_examples(
    function_name=func.name,
    parameters=func.parameters,
    description=enhanced_desc
)

3. 监听文件变更

from auto_doc_generator import DocumentWatcher

# 创建监听器
watcher = DocumentWatcher(
    input_dir="src/",
    output_dir="docs/",
    format="markdown",
    use_ai=True,
    model="llama3"
)

# 开始监听
watcher.start_watching()

---

🎨 模板系统

内置模板

1. default: 标准 Markdown API 文档
2. python: Python 专用模板
3. javascript: JavaScript 专用模板
4. html: HTML 输出模板
5. minimal: 最小化文档模板

自定义模板

创建自定义 Jinja2 模板：

<!-- templates/custom/api.jinja2 -->
# {{ module_name }} API Reference

{{ module_description }}

## Functions

{% for func in functions %}
### `{{ func.name }}()`

{{ func.description }}

**Parameters:**
{% for param in func.parameters %}
- `{{ param.name }}` ({{ param.type }}): {{ param.description }}
{% endfor %}

**Returns:** {{ func.return_type }}

{% endfor %}

---

🔧 配置文件

doc-gen.yaml:

project_name: myproject
description: My Project
author: Your Name
license: MIT

# 生成配置
input: src/
output: docs/
format: markdown
template: default

# AI 配置
ai_enabled: true
model: llama3
local: true

# Git Hooks
git_hooks:
  pre_commit: true
  post_commit: false

# CI/CD
github_actions:
  enabled: true
  branches: [main, master]

---

📊 性能指标

指标	目标	实测
文档生成	< 30 秒/项目	~15 秒（50 文件）
提取准确率	> 90%	~95%
模板加载	< 1 秒	~0.3 秒
AI 增强	< 10 秒/文档	~5 秒

---

🛠️ 命令参考

generate - 生成文档

auto-doc-generator generate [options]

Options:
  --input, -i      输入文件或目录（必需）
  --output, -o     输出目录（默认：docs/）
  --format, -f     输出格式（markdown/html/json）
  --ai             启用 AI 增强
  --model          AI 模型名称（默认：llama3）
  --template, -t   模板名称（默认：default）
  --language, -l   编程语言（python/javascript/bash/auto）
  --recursive, -r  递归处理目录（默认：True）
  --verbose, -v    详细输出

watch - 监听文件变更

auto-doc-generator watch [options]

Options:
  --input, -i      输入目录（必需）
  --output, -o     输出目录（默认：docs/）
  --format, -f     输出格式（默认：markdown）
  --ai             启用 AI 增强
  --model          AI 模型名称
  --interval       检查间隔（秒，默认：5）

init - 初始化配置

auto-doc-generator init [options]

Options:
  --project, -p    项目名称（必需）
  --description, -d 项目描述
  --author, -a     作者
  --license        许可证（默认：MIT）

template - 管理模板

auto-doc-generator template <action> [options]

Actions:
  list             列出可用模板
  show             显示模板内容
  create           创建自定义模板

Options:
  --name, -n       模板名称

---

📦 依赖说明

核心依赖

• tree-sitter: 代码解析引擎
• jinja2: 模板引擎
• markdown: Markdown 渲染
• pygments: 语法高亮
• watchdog: 文件监听

可选依赖

• ollama: 本地 AI 模型
• weasyprint: PDF 生成
• openai: 云端 AI 模型

---

🤝 最佳实践

1. 定期更新文档: 使用 watch 模式自动更新
2. 补充注释: 保持代码注释的完整性
3. 使用 AI 增强: 提升文档质量
4. 版本控制: 将文档纳入 Git 管理
5. 模板定制: 根据项目需求定制模板

---

🐛 故障排除

问题1: tree-sitter 导入失败

# 解决方案：安装 tree-sitter 语言包
pip install tree-sitter-python

问题2: AI 增强失败

# 解决方案：确保 Ollama 已安装并运行
ollama pull llama3
ollama serve

问题3: 生成文档为空

# 解决方案：检查代码注释是否完整
# 确保函数/类都有 docstring

---

📝 许可证

MIT License

Copyright (c) 2026 思捷娅科技 (SJYKJ)

免费使用、修改和重新分发时，需注明出处。

出处：

• GitHub: https://github.com/zhaog100/openclaw-skills
• ClawHub: https://clawhub.com
• 创建者: 思捷娅科技 (SJYKJ)

---

🔗 相关链接

• GitHub: https://github.com/zhaog100/openclaw-skills
• ClawHub: https://clawhub.com/skills/auto-document-generator
• 文档: https://github.com/zhaog100/openclaw-skills/tree/master/skills/auto-document-generator/docs
• 问题反馈: https://github.com/zhaog100/openclaw-skills/issues

---

最后更新：2026-03-16
版本：v1.0.0
状态：✅ 已完成