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>
This commit is contained in:
243
docs/SUMMARY.md
Normal file
243
docs/SUMMARY.md
Normal file
@@ -0,0 +1,243 @@
|
||||
# Macro Split 项目文档总结
|
||||
|
||||
本文档汇总了仓库中所有 Markdown 文件的内容摘要。
|
||||
|
||||
---
|
||||
|
||||
## 1. README.md (项目主文档)
|
||||
|
||||
**位置**: `/README.md`
|
||||
|
||||
### 项目简介
|
||||
Macrolactone Fragmenter 是一个专业的大环内酯（12-20元环）侧链断裂和分析工具。
|
||||
|
||||
### 主要特性
|
||||
- **智能环原子编号** - 支持 12-20 元环，基于内酯结构的固定编号系统
|
||||
- **自动侧链断裂** - 智能识别并断裂所有侧链
|
||||
- **强大的可视化** - SVG + PNG 输出
|
||||
- **多种导出格式** - JSON、CSV、DataFrame
|
||||
- **批量处理** - 支持 2000+ 分子的大规模分析
|
||||
|
||||
### 安装方式
|
||||
```bash
|
||||
# 使用 Pixi（推荐）
|
||||
pixi install && pixi shell
|
||||
|
||||
# 使用 Pip
|
||||
conda install -c conda-forge rdkit
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
### 基本用法
|
||||
```python
|
||||
from src.macrolactone_fragmenter import MacrolactoneFragmenter
|
||||
fragmenter = MacrolactoneFragmenter(ring_size=16)
|
||||
result = fragmenter.process_molecule(smiles, parent_id="mol_001")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. CLEANUP_SUMMARY.md (清理总结)
|
||||
|
||||
**位置**: `/CLEANUP_SUMMARY.md`
|
||||
|
||||
### 内容概要
|
||||
记录了项目根目录的清理工作：
|
||||
- **保留的文件**: README.md, DOCUMENTATION_GUIDE.md, QUICK_COMMANDS.md
|
||||
- **归档的文件**: 14 个历史文档已移至 `archive/` 目录
|
||||
- **清理前**: 17 个 MD 文件，约 120KB
|
||||
- **清理后**: 3 个核心 MD 文件 + 30+ 个文档系统文件
|
||||
|
||||
---
|
||||
|
||||
## 3. DOCUMENTATION_GUIDE.md (文档系统指南)
|
||||
|
||||
**位置**: `/DOCUMENTATION_GUIDE.md`
|
||||
|
||||
### 文档系统特性
|
||||
- 使用 **MkDocs + Material 主题 + mkdocstrings** 构建
|
||||
- 支持中文、深色/浅色模式
|
||||
- 自动从代码生成 API 文档
|
||||
- 支持数学公式（MathJax）
|
||||
|
||||
### 常用命令
|
||||
```bash
|
||||
# 本地预览
|
||||
pixi run mkdocs serve
|
||||
|
||||
# 构建静态网站
|
||||
pixi run mkdocs build
|
||||
|
||||
# 部署到 GitHub Pages
|
||||
pixi run mkdocs gh-deploy
|
||||
```
|
||||
|
||||
### 添加新文档步骤
|
||||
1. 在 `docs/` 创建 `.md` 文件
|
||||
2. 编辑内容
|
||||
3. 在 `mkdocs.yml` 的 `nav` 部分添加链接
|
||||
4. 运行预览验证
|
||||
|
||||
---
|
||||
|
||||
## 4. IMPLEMENTATION_SUMMARY.md (实现总结)
|
||||
|
||||
**位置**: `/IMPLEMENTATION_SUMMARY.md`
|
||||
|
||||
### MacroLactoneAnalyzer 封装
|
||||
新增 `src/macro_lactone_analyzer.py` 模块，提供：
|
||||
|
||||
#### 静态方法
|
||||
- `detect_ring_sizes(mol)` - 识别环大小
|
||||
- `is_valid_macrolactone(mol, size)` - 验证大环内酯
|
||||
- `analyze_smiles(smiles)` - 单分子分析
|
||||
- `dynamic_smarts_match(smiles, ring_size)` - 动态 SMARTS 匹配
|
||||
|
||||
#### 实例方法
|
||||
- `get_single_ring_info(smiles)` - 单分子详细信息
|
||||
- `analyze_list(smiles_list)` - 批量分析
|
||||
- `classify_molecules(df)` - DataFrame 分类
|
||||
|
||||
### 特性
|
||||
- 高复用性、类型安全、详细错误处理
|
||||
- 支持 12-20 元环分析
|
||||
- 版本号更新至 2.0.0
|
||||
|
||||
---
|
||||
|
||||
## 5. QUICK_COMMANDS.md (快速命令参考)
|
||||
|
||||
**位置**: `/QUICK_COMMANDS.md`
|
||||
|
||||
### 文档命令
|
||||
```bash
|
||||
pixi run mkdocs serve # 启动文档服务器
|
||||
pixi run mkdocs build # 构建静态文档
|
||||
pixi run mkdocs gh-deploy # 部署到 GitHub Pages
|
||||
```
|
||||
|
||||
### 安装命令
|
||||
```bash
|
||||
pixi install && pixi shell # Pixi 方式
|
||||
pip install -e . # 开发模式
|
||||
```
|
||||
|
||||
### 开发工具
|
||||
```bash
|
||||
pixi run black src/ # 格式化代码
|
||||
pixi run flake8 src/ # 检查代码质量
|
||||
pixi run pytest # 运行测试
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. notebooks/README_analyze_ring16.md (Notebook 说明)
|
||||
|
||||
**位置**: `/notebooks/README_analyze_ring16.md`
|
||||
|
||||
### 文件说明
|
||||
- **Notebook**: `analyze_ring16_molecules.ipynb`
|
||||
- **输入**: `../output/ring16_match_smarts.csv` (307个分子)
|
||||
|
||||
### 分析内容
|
||||
1. **分子基本性质**: 分子量、LogP、QED、TPSA 等
|
||||
2. **侧链断裂分析**: 使用 MacrolactoneFragmenter 类
|
||||
3. **分布图绘制**: 4x4 子图布局，位置 3-16 的分布
|
||||
|
||||
### 输出文件
|
||||
- `ring16_molecular_properties_distribution.png`
|
||||
- `atom_count_distribution_ring16.png`
|
||||
- `molecular_weight_distribution_ring16.png`
|
||||
- `ring16_fragments_analysis.csv`
|
||||
|
||||
### 延伸分析建议
|
||||
- LogP/QED/TPSA 分析
|
||||
- SAR 分析（如有活性数据）
|
||||
- 碎片多样性分析
|
||||
- 聚类分析
|
||||
|
||||
---
|
||||
|
||||
## 7. scripts/README.md (脚本使用说明)
|
||||
|
||||
**位置**: `/scripts/README.md`
|
||||
|
||||
### 脚本列表
|
||||
|
||||
#### batch_process_ring16.py
|
||||
- 处理 16 元环分子（1241个）
|
||||
- 输入: `ring16/temp_filtered_complete.csv`
|
||||
- 输出: `output/ring16_fragments/`
|
||||
|
||||
#### batch_process_multi_rings.py
|
||||
- 处理 12-20 元环的所有分子
|
||||
- 自动按环大小分类
|
||||
- 检测并剔除含多个内酯键的分子
|
||||
|
||||
### 输出文件格式
|
||||
```json
|
||||
{
|
||||
"parent_id": "ring16_mol_0",
|
||||
"parent_smiles": "...",
|
||||
"fragments": [
|
||||
{
|
||||
"fragment_smiles": "CC(C)C",
|
||||
"cleavage_position": 5,
|
||||
"atom_count": 4,
|
||||
"molecular_weight": 58.12
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 日志文件
|
||||
- `processing_log_*.txt` - 处理过程
|
||||
- `error_log_*.txt` - 错误记录
|
||||
- `multiple_lactone_log_*.txt` - 多内酯键分子
|
||||
|
||||
---
|
||||
|
||||
## 项目结构概览
|
||||
|
||||
```
|
||||
macro_split/
|
||||
├── src/ # 核心源代码
|
||||
│ ├── macrolactone_fragmenter.py # 高级封装类
|
||||
│ ├── macro_lactone_analyzer.py # 环数分析器
|
||||
│ ├── ring_numbering.py # 环编号系统
|
||||
│ ├── ring_visualization.py # 可视化工具
|
||||
│ └── fragment_dataclass.py # 碎片数据类
|
||||
├── notebooks/ # Jupyter Notebook 示例
|
||||
├── scripts/ # 批量处理脚本
|
||||
├── docs/ # 文档目录
|
||||
├── tests/ # 单元测试
|
||||
├── pyproject.toml # 项目配置
|
||||
├── setup.py # 打包脚本
|
||||
├── pixi.toml # Pixi 环境配置
|
||||
└── mkdocs.yml # 文档配置
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 快速开始
|
||||
|
||||
1. **安装环境**
|
||||
```bash
|
||||
pixi install && pixi shell
|
||||
```
|
||||
|
||||
2. **测试导入**
|
||||
```python
|
||||
from src.macrolactone_fragmenter import MacrolactoneFragmenter
|
||||
fragmenter = MacrolactoneFragmenter(ring_size=16)
|
||||
```
|
||||
|
||||
3. **查看文档**
|
||||
```bash
|
||||
pixi run mkdocs serve
|
||||
# 访问 http://localhost:8000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*文档生成日期: 2025-01-23*
|
||||
Reference in New Issue
Block a user