macro_split/docs/project-docs/DOCUMENTATION_GUIDE.md

# 文档系统使用指南

本项目已完成完整的文档系统搭建，使用 **MkDocs + Material 主题 + mkdocstrings** 构建。

## 📚 文档系统特性

### ✅ 已完成功能

1. **完整的文档结构**
   - 首页和快速开始
   - 详细的用户指南
   - 教程与示例
   - 自动生成的 API 文档
   - 开发者指南

2. **现代化主题**
   - Material Design 风格
   - 支持中文
   - 深色/浅色模式切换
   - 响应式设计

3. **强大的功能**
   - 自动从代码生成 API 文档
   - 搜索功能
   - 代码高亮
   - 数学公式支持（MathJax）
   - 导航标签

4. **打包支持**
   - `setup.py` 和 `pyproject.toml` 配置
   - 支持 `pip install -e .` 开发模式
   - 支持 `pip install .` 常规安装
   - MIT License

## 🚀 使用文档系统

### 本地预览文档

```bash
# 启动开发服务器
pixi run mkdocs serve

# 访问 http://localhost:8000
```

### 构建静态网站

```bash
# 构建文档到 site/ 目录
pixi run mkdocs build
```

### 部署到 GitHub Pages

```bash
# 自动构建并部署
pixi run mkdocs gh-deploy
```

## 📁 文档结构

```
docs/
├── index.md                     # 首页
├── getting-started.md           # 快速开始
├── installation.md              # 安装指南
├── user-guide/                  # 用户指南
│   ├── index.md
│   ├── fragmenter-usage.md      # MacrolactoneFragmenter 使用
│   ├── ring-numbering.md        # 环编号系统
│   ├── visualization.md         # 可视化功能
│   ├── batch-processing.md      # 批量处理
│   └── data-export.md           # 数据导出
├── tutorials/                   # 教程
│   ├── index.md
│   ├── basic-tutorial.md
│   ├── advanced-usage.md
│   └── use-cases.md
├── api/                         # API 文档（自动生成）
│   ├── index.md
│   ├── macrolactone-fragmenter.md
│   ├── fragment-dataclass.md
│   ├── ring-numbering.md
│   ├── ring-visualization.md
│   └── utilities.md
├── development/                 # 开发者指南
│   ├── index.md
│   ├── contributing.md
│   ├── project-structure.md
│   └── testing.md
├── about/                       # 关于
│   ├── index.md
│   ├── changelog.md
│   └── license.md
├── stylesheets/                 # 自定义样式
│   └── extra.css
└── javascripts/                 # 自定义脚本
    └── mathjax.js
```

## 📝 如何添加新文档

### 1. 创建 Markdown 文件

在 `docs/` 目录下创建新的 `.md` 文件：

```bash
# 例如：创建新的教程
touch docs/tutorials/my-new-tutorial.md
```

### 2. 编辑文件内容

使用 Markdown 格式编写内容：

```markdown
# 我的新教程

## 简介

这是一个新教程...

## 示例代码

\`\`\`python
from src.macrolactone_fragmenter import MacrolactoneFragmenter

fragmenter = MacrolactoneFragmenter(ring_size=16)
\`\`\`
```

### 3. 添加到导航

编辑 `mkdocs.yml`，在 `nav` 部分添加链接：

```yaml
nav:
  - 教程与示例:
    - tutorials/index.md
    - 基础教程: tutorials/basic-tutorial.md
    - 我的新教程: tutorials/my-new-tutorial.md  # 新添加
```

### 4. 预览更改

```bash
pixi run mkdocs serve
```

## 🎨 自定义文档

### 修改主题颜色

编辑 `mkdocs.yml` 中的 `theme.palette` 部分：

```yaml
theme:
  palette:
    primary: indigo  # 修改为其他颜色：red, blue, green 等
    accent: indigo
```

### 添加自定义 CSS

编辑 `docs/stylesheets/extra.css`：

```css
/* 自定义样式 */
.my-custom-class {
    color: red;
}
```

### 修改导航结构

编辑 `mkdocs.yml` 中的 `nav` 部分。

## 📖 自动 API 文档

本项目使用 `mkdocstrings` 自动从 Python 代码生成 API 文档。

### 如何添加 API 文档

在 `docs/api/` 目录创建新的 `.md` 文件，使用特殊语法：

```markdown
# 我的模块 API

::: src.my_module.MyClass
    options:
      show_root_heading: true
      show_source: true
      heading_level: 2
```

这会自动提取 `src/my_module.py` 中 `MyClass` 的 docstring 并生成文档。

### Docstring 格式

使用 Google 风格的 docstring：

```python
def my_function(param1: str, param2: int) -> bool:
    """
    函数简短描述。
    
    详细描述...
    
    Args:
        param1: 第一个参数说明
        param2: 第二个参数说明
    
    Returns:
        返回值说明
    
    Raises:
        ValueError: 何时抛出此异常
    
    Example:
        >>> my_function("test", 42)
        True
    """
    pass
```

## 🔍 文档特性

### 代码块

支持语法高亮：

\`\`\`python
from src.macrolactone_fragmenter import MacrolactoneFragmenter
fragmenter = MacrolactoneFragmenter(ring_size=16)
\`\`\`

### 提示框

使用 admonition：

```markdown
!!! note "注意"
    这是一个注意提示。

!!! tip "提示"
    这是一个小贴士。

!!! warning "警告"
    这是一个警告。
```

### 标签页

使用 tabbed：

```markdown
=== "Python"
    \`\`\`python
    print("Hello")
    \`\`\`

=== "Bash"
    \`\`\`bash
    echo "Hello"
    \`\`\`
```

### 数学公式

使用 MathJax：

```markdown
行内公式：\\( E = mc^2 \\)

块公式：
\\[
\\frac{-b \\pm \\sqrt{b^2 - 4ac}}{2a}
\\]
```

## 📦 打包和发布

### 本地安装

```bash
# 开发模式
pip install -e .

# 常规安装
pip install .
```

### 构建分发包

```bash
# 安装构建工具
pip install build

# 构建
python -m build

# 会生成：
# dist/macrolactone_fragmenter-1.2.0.tar.gz
# dist/macrolactone_fragmenter-1.2.0-py3-none-any.whl
```

### 发布到 PyPI

```bash
# 安装 twine
pip install twine

# 上传到 PyPI
twine upload dist/*

# 或先上传到 TestPyPI 测试
twine upload --repository testpypi dist/*
```

## 🚀 持续集成（CI）

可以配置 GitHub Actions 自动构建和部署文档。

创建 `.github/workflows/docs.yml`：

```yaml
name: Deploy Docs

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: 3.x
      - run: pip install mkdocs-material mkdocstrings[python]
      - run: mkdocs gh-deploy --force
```

## ℹ️ 注意事项

1. **RDKit 依赖**：PyPI 安装后仍需通过 conda 安装 RDKit
2. **文档更新**：修改代码后记得更新 docstring
3. **锚点链接**：使用英文标题更容易创建稳定的锚点
4. **图片路径**：放在 `docs/assets/images/` 目录

## 📊 项目状态

✅ 所有任务已完成：

1. ✅ 安装 MkDocs、Material 主题、mkdocstrings
2. ✅ 创建完整的文档结构
3. ✅ 自动生成 API 文档
4. ✅ 创建 setup.py 和 pyproject.toml
5. ✅ 支持 pip install 安装
6. ✅ 更新 README.md
7. ✅ 测试文档构建

## 🎉 完成！

文档系统已完全搭建完成，您可以：

1. 运行 `pixi run mkdocs serve` 查看文档
2. 使用 `pip install -e .` 安装项目
3. 继续完善教程和示例内容
4. 准备发布到 PyPI

---

**祝您使用愉快！** 🚀