macrolactone-toolkit/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

🚀 使用文档系统

本地预览文档

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

# 访问 http://localhost:8000

构建静态网站

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

部署到 GitHub Pages

# 自动构建并部署
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 文件：

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

2. 编辑文件内容

使用 Markdown 格式编写内容：

# 我的新教程

## 简介

这是一个新教程...

## 示例代码

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

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

3. 添加到导航

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

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

4. 预览更改

pixi run mkdocs serve

🎨 自定义文档

修改主题颜色

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

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

添加自定义 CSS

编辑 docs/stylesheets/extra.css：

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

修改导航结构

编辑 mkdocs.yml 中的 nav 部分。

📖 自动 API 文档

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

如何添加 API 文档

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

# 我的模块 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：

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：

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

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

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

标签页

使用 tabbed：

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

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

数学公式

使用 MathJax：

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

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

📦 打包和发布

本地安装

# 开发模式
pip install -e .

# 常规安装
pip install .

构建分发包

# 安装构建工具
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

# 安装 twine
pip install twine

# 上传到 PyPI
twine upload dist/*

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

🚀 持续集成（CI）

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

创建 .github/workflows/docs.yml：

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

---

祝您使用愉快！ 🚀