hotwa
a768d26e47
- 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>
244 lines
5.9 KiB
Markdown
244 lines
5.9 KiB
Markdown
# 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*
|