documentation-tools

---
name: documentation-tools
description: 文档工具：MkDocs/Stroy、Sphinx/ReadTheDocs、API文档自动生成.
triggers:
  - 文档 / 文档生成
  - MkDocs / Sphinx
  - API 文档 / 知识库
---

# 文档工具

## 选型

```
API 文档     → FastAPI 自带 Swagger（/docs）
项目文档     → MkDocs（Material 主题，好看）
Python 库文档 → Sphinx + ReadTheDocs
知识库       → Obsidian（你已经在用）
GitHub Pages → 托管静态文档（免费）
```

## MkDocs + Material

```bash
pip install mkdocs mkdocs-material
mkdocs new my-docs
cd my-docs
mkdocs serve  # 本地预览 http://localhost:8000
```

```yaml
# mkdocs.yml
site_name: 我的项目文档
theme:
  name: material
  features:
    - navigation.tabs
    - search.highlight
nav:
  - 首页: index.md
  - 快速开始: quickstart.md
  - API 参考: api.md
  - 常见问题: faq.md
```

## Sphinx（Python 生态标准）

```bash
pip install sphinx
sphinx-quickstart docs
cd docs
make html  # 生成 HTML 文档
```

```python
# 自动从 docstring 生成 API 文档
def my_function(param1, param2):
    """
    函数简述。

    :param param1: 第一个参数说明
    :param param2: 第二个参数说明
    :returns: 返回值说明
    :raises ValueError: 参数无效时

    示例::

        result = my_function(1, 2)
    """
    pass
```

## 文档即代码

```
好处：
1. 文档和代码放同一个仓库（同步更新）
2. Markdown 写，任何人能贡献
3. CI/CD 自动构建部署
4. Git 追踪文档变更历史
```

## 你的知识库已经在用最佳实践

```
D:\Hermes\knowledge-base\
  → Obsidian 管理
  → Markdown 格式
  → 双向链接
  → Mermaid 图表
  → Git 版本控制（如果放在 git 仓库里）

这就是"文档即代码"的最佳实践！
```