refactor: 重构文档结构，采用渐进式信息披露模式
将 README.md 拆分为多个专题文档，减少认知负荷： - 用户文档迁移到 docs/ (用户指南、元素、模板、参考等) - 开发文档迁移到 docs/development/ (架构、模块、规范) - README.md 精简至 ~290 行，仅保留概览和导航 - 删除 README_DEV.md，内容已迁移 - 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
This commit is contained in:
221
docs/user-guide.md
Normal file
221
docs/user-guide.md
Normal file
@@ -0,0 +1,221 @@
|
||||
# 用户指南
|
||||
|
||||
本指南提供 yaml2pptx 的完整使用说明。
|
||||
|
||||
## 功能特性
|
||||
|
||||
- **YAML 声明式语法** - 使用简单易读的 YAML 定义演示文稿
|
||||
- **智能验证** - 转换前自动检查 YAML 文件，提前发现问题
|
||||
- **模板系统** - 支持参数化模板，复用幻灯片布局
|
||||
- **丰富的元素类型** - 文本、图片、形状、表格
|
||||
- **实时预览** - 浏览器预览模式，支持热重载
|
||||
- **灵活尺寸** - 支持 16:9 和 4:3 两种宽高比
|
||||
- **模块化架构** - 易于扩展和维护
|
||||
|
||||
## 安装
|
||||
|
||||
本工具使用 [uv](https://github.com/astral-sh/uv) 管理依赖。项目依赖在 pyproject.toml 中声明，运行时会自动安装所需的 Python 包。
|
||||
|
||||
## 基本用法
|
||||
|
||||
### 转换 YAML 为 PPTX
|
||||
|
||||
```bash
|
||||
# 转换 YAML 为 PPTX
|
||||
uv run yaml2pptx.py convert presentation.yaml output.pptx
|
||||
|
||||
# 自动生成输出文件名
|
||||
uv run yaml2pptx.py convert presentation.yaml
|
||||
|
||||
# 使用模板库
|
||||
uv run yaml2pptx.py convert presentation.yaml output.pptx --template ./templates.yaml
|
||||
```
|
||||
|
||||
### 实时预览
|
||||
|
||||
```bash
|
||||
# 启动预览服务器（自动打开浏览器）
|
||||
uv run yaml2pptx.py preview presentation.yaml
|
||||
|
||||
# 指定端口
|
||||
uv run yaml2pptx.py preview presentation.yaml --port 8080
|
||||
|
||||
# 允许局域网访问
|
||||
uv run yaml2pptx.py preview presentation.yaml --host 0.0.0.0
|
||||
|
||||
# 不自动打开浏览器
|
||||
uv run yaml2pptx.py preview presentation.yaml --no-browser
|
||||
```
|
||||
|
||||
预览模式会自动监听文件变化，修改 YAML 文件后浏览器会自动刷新。
|
||||
|
||||
### 验证功能
|
||||
|
||||
在转换前验证 YAML 文件，提前发现问题：
|
||||
|
||||
```bash
|
||||
# 独立验证命令
|
||||
uv run yaml2pptx.py check presentation.yaml
|
||||
|
||||
# 使用模板时验证
|
||||
uv run yaml2pptx.py check presentation.yaml --template ./templates.yaml
|
||||
```
|
||||
|
||||
验证功能会检查：
|
||||
- YAML 语法和结构
|
||||
- 元素是否超出页面范围
|
||||
- 图片和模板文件是否存在
|
||||
- 颜色格式是否正确
|
||||
- 字体大小是否合理
|
||||
- 表格数据是否一致
|
||||
|
||||
**自动验证**：转换时默认会自动验证，如果发现错误会终止转换。可以使用 `--skip-validation` 跳过验证：
|
||||
|
||||
```bash
|
||||
# 跳过自动验证
|
||||
uv run yaml2pptx.py convert presentation.yaml --skip-validation
|
||||
```
|
||||
|
||||
**验证结果示例**：
|
||||
|
||||
```
|
||||
正在检查 YAML 文件...
|
||||
|
||||
- 错误 (2):
|
||||
[幻灯片 2, 元素 1] 无效的颜色格式: red (应为 #RRGGBB)
|
||||
[幻灯片 3, 元素 2] 图片文件不存在: logo.png
|
||||
|
||||
- 警告 (1):
|
||||
[幻灯片 1, 元素 1] 元素右边界超出: 10.50 > 10
|
||||
|
||||
检查完成: 发现 2 个错误, 1 个警告
|
||||
```
|
||||
|
||||
- **ERROR**：阻止转换的严重问题（文件不存在、语法错误等）
|
||||
- **WARNING**：影响视觉效果的问题（元素超出页面、字体太小等）
|
||||
- **INFO**：优化建议
|
||||
|
||||
## YAML 语法基础
|
||||
|
||||
### 最小示例
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
size: "16:9" # 或 "4:3"
|
||||
|
||||
slides:
|
||||
- background:
|
||||
color: "#ffffff"
|
||||
elements:
|
||||
- type: text
|
||||
box: [1, 1, 8, 1]
|
||||
content: "Hello, World!"
|
||||
font:
|
||||
size: 44
|
||||
bold: true
|
||||
color: "#333333"
|
||||
align: center
|
||||
```
|
||||
|
||||
### description 字段
|
||||
|
||||
`metadata.description` 字段用于描述整个演示文稿的概要和用途，仅用于文档目的，不影响生成的 PPTX 文件：
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
size: "16:9"
|
||||
description: "2024年度项目进展总结，包含背景、成果和展望"
|
||||
```
|
||||
|
||||
### 使用模板
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
size: "16:9"
|
||||
|
||||
slides:
|
||||
- template: title-slide
|
||||
vars:
|
||||
title: "我的演示文稿"
|
||||
subtitle: "使用 yaml2pptx 创建"
|
||||
author: "张三"
|
||||
|
||||
- template: content-slide
|
||||
vars:
|
||||
title: "功能概览"
|
||||
content: "yaml2pptx 支持多种元素类型..."
|
||||
```
|
||||
|
||||
## 使用技巧
|
||||
|
||||
1. **开发流程**：使用预览模式实时查看效果，确认无误后再生成 PPTX
|
||||
2. **模板复用**：为常用布局创建模板，保持演示文稿风格一致
|
||||
3. **相对路径**：图片路径相对于 YAML 文件位置，便于项目管理
|
||||
4. **文本换行**：文本框默认启用自动换行，无需手动处理长文本
|
||||
|
||||
## 扩展性
|
||||
|
||||
yaml2pptx 采用模块化架构，易于扩展：
|
||||
|
||||
- **添加新元素类型**：定义新的元素数据类和渲染方法
|
||||
- **添加新渲染器**：支持输出到其他格式（如 PDF）
|
||||
- **自定义模板**：创建符合你需求的模板库
|
||||
|
||||
详见 [开发文档](../development/extending.md)。
|
||||
|
||||
## 依赖项
|
||||
|
||||
- `python-pptx` - PowerPoint 文件生成
|
||||
- `pyyaml` - YAML 解析
|
||||
- `flask` - 预览服务器
|
||||
- `watchdog` - 文件监听
|
||||
|
||||
依赖在 pyproject.toml 中声明，由 uv 自动管理，无需手动安装。
|
||||
|
||||
## 测试
|
||||
|
||||
项目包含完整的测试套件，使用 pytest 框架。
|
||||
|
||||
### 运行测试
|
||||
|
||||
```bash
|
||||
# 安装测试依赖
|
||||
uv pip install -e ".[dev]"
|
||||
|
||||
# 运行所有测试
|
||||
uv run pytest
|
||||
|
||||
# 运行特定类型的测试
|
||||
uv run pytest tests/unit/ # 单元测试
|
||||
uv run pytest tests/integration/ # 集成测试
|
||||
uv run pytest tests/e2e/ # 端到端测试
|
||||
|
||||
# 运行特定测试文件
|
||||
uv run pytest tests/unit/test_elements.py
|
||||
|
||||
# 显示详细输出
|
||||
uv run pytest -v
|
||||
|
||||
# 显示测试覆盖率
|
||||
uv run pytest --cov=. --cov-report=html
|
||||
```
|
||||
|
||||
### 测试结构
|
||||
|
||||
```
|
||||
tests/
|
||||
├── unit/ # 单元测试 - 测试各模块独立功能
|
||||
├── integration/ # 集成测试 - 测试模块间协作
|
||||
├── e2e/ # 端到端测试 - 测试完整用户场景
|
||||
└── fixtures/ # 测试数据
|
||||
```
|
||||
|
||||
## 贡献
|
||||
|
||||
欢迎贡献代码、报告问题或提出建议！
|
||||
|
||||
开发者请参阅 [开发文档](../development/) 了解代码结构和开发规范。
|
||||
|
||||
## 许可证
|
||||
|
||||
MIT License
|
||||
Reference in New Issue
Block a user