Move project docs to docs/project-docs and update references

- Move AGENTS.md, CLEANUP_SUMMARY.md, DOCUMENTATION_GUIDE.md, IMPLEMENTATION_SUMMARY.md, QUICK_COMMANDS.md to docs/project-docs/ - Update AGENTS.md to include splicing module documentation - Update mkdocs.yml navigation to include project-docs section - Update .gitignore to track docs/ directory - Add docs/plans/ splicing design documents Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-18 17:56:03 +08:00
parent 68f171ad1d
commit a768d26e47
10 changed files with 555 additions and 7 deletions
--- a/docs/project-docs/DOCUMENTATION_GUIDE.md
+++ b/docs/project-docs/DOCUMENTATION_GUIDE.md
@@ -0,0 +1,377 @@
+# 文档系统使用指南
+
+本项目已完成完整的文档系统搭建，使用 **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
+
+---
+
+**祝您使用愉快！** 🚀
+