# 构建脚本说明

本目录包含用于项目构建和发布的辅助脚本。

## build_readme.py

用于在发布到 PyPI 时，将文档目录中的指南文件合并到 README.md 中。

### 功能

1. 读取 `doc/guide_*.md` 文件
2. 将内容合并到 README.md
3. 生成完整的 README 用于 PyPI 展示

### 使用方法

#### 方法 1: 使用 Makefile（推荐）

```bash
# 发布到 PyPI（自动处理 README）
make upload

# 发布到 TestPyPI（测试用）
make upload-test

# 仅构建 README（查看效果）
make build-readme
```

#### 方法 2: 直接运行脚本

```bash
# 1. 构建完整 README（生成 README_BUILD.md）
python scripts/build_readme.py

# 2. 检查构建结果
cat README_BUILD.md

# 3. 如果满意，替换原始 README
python scripts/build_readme.py --backup  # 先备份
python scripts/build_readme.py --use-build  # 替换

# 4. 构建和上传包
python -m build
twine upload dist/*

# 5. 发布后恢复原始 README
python scripts/build_readme.py --restore
```

### 命令参数

```bash
python scripts/build_readme.py [options]

Options:
  --root PATH      指定项目根目录（默认自动检测）
  --backup         备份原始 README.md
  --restore        恢复原始 README.md
  --use-build      使用构建版本替换原始 README（发布前）
```

### 工作流程

1. **开发阶段**: 维护 `README.md` 和 `doc/guide_*.md`
2. **发布前**: 运行 `make prepare-release` 合并文档
3. **上传 PyPI**: 运行 `make upload`
4. **发布后**: 自动恢复原始 README

### 在 README 中自定义插入位置

如果你想控制指南内容的插入位置，在 README.md 中添加标记：

```markdown
<!-- GUIDES_CONTENT -->
```

脚本会在这个位置插入所有指南内容。如果没有这个标记，内容会追加到文件末尾。

### 示例

假设你有以下文件：

```
doc/
├── guide_orm.md       # ORM 使用指南
├── guide_tasks.md     # 定时任务指南
└── guide_events.md    # 事件系统指南
```

运行构建后，README_BUILD.md 将包含：

```markdown
[原始 README 内容]

---

# 📖 详细指南

## 指南目录
1. [ORM 数据库操作指南](#guide-orm)
2. [定时任务调度器使用指南](#guide-tasks)
3. [事件系统使用指南](#guide-events)

---

[guide_orm.md 的完整内容]

---

[guide_tasks.md 的完整内容]

---

[guide_events.md 的完整内容]
```

### 注意事项

1. 脚本会自动处理标题层级，避免重复的一级标题
2. 生成的 README_BUILD.md 不会提交到 git
3. 原始 README.md 会在发布后自动恢复
4. 备份文件 README.original.md 不会提交到 git

### 故障排除

**问题**: 构建的 README 太长

**解决**: 考虑缩减指南内容或只保留关键部分

**问题**: PyPI 显示格式错误

**解决**: 检查 Markdown 语法，确保代码块正确闭合

**问题**: 想排除某些指南文件

**解决**: 重命名文件不使用 `guide_` 前缀，或移到其他目录
