refactor: 重构文档结构，采用渐进式信息披露模式
将 README.md 拆分为多个专题文档，减少认知负荷： - 用户文档迁移到 docs/ (用户指南、元素、模板、参考等) - 开发文档迁移到 docs/development/ (架构、模块、规范) - README.md 精简至 ~290 行，仅保留概览和导航 - 删除 README_DEV.md，内容已迁移 - 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
This commit is contained in:
17
docs/reference/_index.md
Normal file
17
docs/reference/_index.md
Normal file
@@ -0,0 +1,17 @@
|
||||
# API 参考文档
|
||||
|
||||
本目录包含各种 API 参考文档。
|
||||
|
||||
## 参考主题
|
||||
|
||||
- [命令行选项](commands.md) - 所有命令和参数
|
||||
- [坐标系统](coordinates.md) - 位置和尺寸单位
|
||||
- [颜色格式](colors.md) - 颜色表示方法
|
||||
- [验证功能](validation.md) - YAML 验证说明
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [用户指南](../user-guide.md) - 完整使用说明
|
||||
- [故障排查](../troubleshooting.md) - 常见问题解决
|
||||
|
||||
[返回文档索引](../README.md)
|
||||
141
docs/reference/colors.md
Normal file
141
docs/reference/colors.md
Normal file
@@ -0,0 +1,141 @@
|
||||
# 颜色格式
|
||||
|
||||
yaml2pptx 支持两种十六进制颜色格式。
|
||||
|
||||
## 支持的格式
|
||||
|
||||
### 短格式 #RGB
|
||||
|
||||
3 位十六进制，每位颜色值重复一次：
|
||||
|
||||
```yaml
|
||||
color: "#fff" # 白色 (#ffffff)
|
||||
color: "#000" # 黑色 (#000000)
|
||||
color: "#f00" # 红色 (#ff0000)
|
||||
color: "#0f0" # 绿色 (#00ff00)
|
||||
color: "#00f" # 蓝色 (#0000ff)
|
||||
```
|
||||
|
||||
### 完整格式 #RRGGBB
|
||||
|
||||
6 位十六进制，标准的颜色表示：
|
||||
|
||||
```yaml
|
||||
color: "#ffffff" # 白色
|
||||
color: "#000000" # 黑色
|
||||
color: "#ff0000" # 红色
|
||||
color: "#00ff00" # 绿色
|
||||
color: "#0000ff" # 蓝色
|
||||
```
|
||||
|
||||
## 常用颜色参考
|
||||
|
||||
### 基础颜色
|
||||
|
||||
| 颜色 | 短格式 | 完整格式 |
|
||||
|------|--------|----------|
|
||||
| 黑色 | `#000` | `#000000` |
|
||||
| 白色 | `#fff` | `#ffffff` |
|
||||
| 红色 | `#f00` | `#ff0000` |
|
||||
| 绿色 | `#0f0` | `#00ff00` |
|
||||
| 蓝色 | `#00f` | `#0000ff` |
|
||||
|
||||
### 常用色彩
|
||||
|
||||
| 颜色 | 完整格式 | 说明 |
|
||||
|------|----------|------|
|
||||
| 灰色 | `#808080` | 中性灰 |
|
||||
| 深灰 | `#333333` | 深灰色 |
|
||||
| 浅灰 | `#cccccc` | 浅灰色 |
|
||||
| 黄色 | `#ffff00` | 纯黄色 |
|
||||
| 青色 | `#00ffff` | 纯青色 |
|
||||
| 品红 | `#ff00ff` | 纯品红 |
|
||||
|
||||
### Material Design 色彩
|
||||
|
||||
| 颜色 | 完整格式 | 说明 |
|
||||
|------|----------|------|
|
||||
| 红色 | `#f44336` | Material Red |
|
||||
| 粉色 | `#e91e63` | Material Pink |
|
||||
| 紫色 | `#9c27b0` | Material Purple |
|
||||
| 深紫 | `#673ab7` | Material Deep Purple |
|
||||
| 靛蓝 | `#3f51b5` | Material Indigo |
|
||||
| 蓝色 | `#2196f3` | Material Blue |
|
||||
| 浅蓝 | `#03a9f4` | Material Light Blue |
|
||||
| 青色 | `#00bcd4` | Material Cyan |
|
||||
| 蓝绿 | `#009688` | Material Teal |
|
||||
| 绿色 | `#4caf50` | Material Green |
|
||||
| 浅绿 | `#8bc34a` | Material Light Green |
|
||||
| 橙色 | `#ff9800` | Material Orange |
|
||||
| 深橙 | `#ff5722` | Material Deep Orange |
|
||||
|
||||
## 使用示例
|
||||
|
||||
### 文本颜色
|
||||
|
||||
```yaml
|
||||
- type: text
|
||||
content: "红色文本"
|
||||
font:
|
||||
color: "#ff0000"
|
||||
```
|
||||
|
||||
### 形状填充
|
||||
|
||||
```yaml
|
||||
- type: shape
|
||||
box: [1, 1, 4, 2]
|
||||
shape: rectangle
|
||||
fill: "#3498db" # 蓝色
|
||||
```
|
||||
|
||||
### 边框颜色
|
||||
|
||||
```yaml
|
||||
- type: shape
|
||||
box: [1, 1, 4, 2]
|
||||
shape: rectangle
|
||||
fill: "#ffffff"
|
||||
line:
|
||||
color: "#000000"
|
||||
width: 2
|
||||
```
|
||||
|
||||
### 表格样式
|
||||
|
||||
```yaml
|
||||
- type: table
|
||||
position: [1, 1]
|
||||
col_widths: [2, 2, 2]
|
||||
data: [...]
|
||||
style:
|
||||
header_bg: "#4a90e2"
|
||||
header_font:
|
||||
color: "#ffffff"
|
||||
```
|
||||
|
||||
## 颜色验证
|
||||
|
||||
系统会自动验证颜色格式：
|
||||
|
||||
- **短格式**：`/#[0-9a-fA-F]{3}/`
|
||||
- **完整格式**：`/#[0-9a-fA-F]{6}/`
|
||||
|
||||
无效的颜色格式会导致验证错误：
|
||||
|
||||
```
|
||||
[幻灯片 1, 元素 1] 无效的颜色格式: red (应为 #RRGGBB)
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 颜色代码必须以 `#` 开头
|
||||
- 不支持颜色名称（如 `red`、`blue`）
|
||||
- 不支持 RGB/RGBA 格式（如 `rgb(255, 0, 0)`）
|
||||
- 大小写均可（`#fff` 和 `#FFF` 等效）
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [坐标系统](coordinates.md) - 位置和尺寸单位
|
||||
|
||||
[返回文档索引](../README.md)
|
||||
123
docs/reference/commands.md
Normal file
123
docs/reference/commands.md
Normal file
@@ -0,0 +1,123 @@
|
||||
# 命令行选项
|
||||
|
||||
yaml2pptx 提供三个主要命令：check、convert、preview。
|
||||
|
||||
## check 命令
|
||||
|
||||
验证 YAML 文件的正确性。
|
||||
|
||||
### 语法
|
||||
|
||||
```bash
|
||||
uv run yaml2pptx.py check <input> [--template <path>]
|
||||
```
|
||||
|
||||
### 选项
|
||||
|
||||
| 选项 | 说明 |
|
||||
|------|------|
|
||||
| `input` | 输入的 YAML 文件路径（必需） |
|
||||
| `--template` | 模板库文件路径 |
|
||||
|
||||
### 示例
|
||||
|
||||
```bash
|
||||
# 验证基本文件
|
||||
uv run yaml2pptx.py check presentation.yaml
|
||||
|
||||
# 验证使用模板的文件
|
||||
uv run yaml2pptx.py check presentation.yaml --template ./templates.yaml
|
||||
```
|
||||
|
||||
## convert 命令
|
||||
|
||||
将 YAML 文件转换为 PPTX 文件。
|
||||
|
||||
### 语法
|
||||
|
||||
```bash
|
||||
uv run yaml2pptx.py convert <input> [output] [options]
|
||||
```
|
||||
|
||||
### 选项
|
||||
|
||||
| 选项 | 说明 |
|
||||
|------|------|
|
||||
| `input` | 输入的 YAML 文件路径（必需） |
|
||||
| `output` | 输出的 PPTX 文件路径（可选） |
|
||||
| `--template` | 模板库文件路径 |
|
||||
| `--skip-validation` | 跳过自动验证 |
|
||||
| `--force` / `-f` | 强制覆盖已存在文件 |
|
||||
|
||||
### 示例
|
||||
|
||||
```bash
|
||||
# 基本转换（自动生成输出文件名）
|
||||
uv run yaml2pptx.py convert presentation.yaml
|
||||
|
||||
# 指定输出文件
|
||||
uv run yaml2pptx.py convert presentation.yaml output.pptx
|
||||
|
||||
# 使用模板库
|
||||
uv run yaml2pptx.py convert presentation.yaml output.pptx --template ./templates.yaml
|
||||
|
||||
# 跳过验证
|
||||
uv run yaml2pptx.py convert presentation.yaml --skip-validation
|
||||
|
||||
# 强制覆盖
|
||||
uv run yaml2pptx.py convert presentation.yaml output.pptx --force
|
||||
```
|
||||
|
||||
## preview 命令
|
||||
|
||||
启动预览服务器，实时查看演示文稿效果。
|
||||
|
||||
### 语法
|
||||
|
||||
```bash
|
||||
uv run yaml2pptx.py preview <input> [options]
|
||||
```
|
||||
|
||||
### 选项
|
||||
|
||||
| 选项 | 说明 |
|
||||
|------|------|
|
||||
| `input` | 输入的 YAML 文件路径（必需） |
|
||||
| `--template` | 模板库文件路径 |
|
||||
| `--port` | 服务器端口（默认：随机端口 30000-40000） |
|
||||
| `--host` | 主机地址（默认：127.0.0.1） |
|
||||
| `--no-browser` | 不自动打开浏览器 |
|
||||
|
||||
### 示例
|
||||
|
||||
```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
|
||||
|
||||
# 使用模板
|
||||
uv run yaml2pptx.py preview presentation.yaml --template ./templates.yaml
|
||||
```
|
||||
|
||||
## 通用选项
|
||||
|
||||
所有命令都支持以下行为：
|
||||
|
||||
- 自动安装依赖（通过 uv）
|
||||
- 显示友好的错误信息
|
||||
- 支持相对路径和绝对路径
|
||||
|
||||
## 退出代码
|
||||
|
||||
- `0` - 成功
|
||||
- `1` - 错误（文件不存在、验证失败等）
|
||||
|
||||
[返回文档索引](../README.md)
|
||||
154
docs/reference/coordinates.md
Normal file
154
docs/reference/coordinates.md
Normal file
@@ -0,0 +1,154 @@
|
||||
# 坐标系统
|
||||
|
||||
yaml2pptx 使用英寸（inch）作为位置和尺寸的单位。
|
||||
|
||||
## 基本概念
|
||||
|
||||
- **单位**：英寸 (inch)
|
||||
- **原点**：幻灯片左上角 (0, 0)
|
||||
- **方向**：X 轴向右，Y 轴向下
|
||||
|
||||
## 幻灯片尺寸
|
||||
|
||||
### 16:9 宽高比
|
||||
|
||||
- 尺寸：10" × 5.625"
|
||||
- 宽度：10 英寸
|
||||
- 高度：5.625 英寸
|
||||
|
||||
### 4:3 宽高比
|
||||
|
||||
- 尺寸：10" × 7.5"
|
||||
- 宽度：10 英寸
|
||||
- 高度：7.5 英寸
|
||||
|
||||
## box 属性
|
||||
|
||||
`box` 属性用于指定元素的位置和尺寸：
|
||||
|
||||
```yaml
|
||||
box: [x, y, width, height]
|
||||
```
|
||||
|
||||
| 参数 | 说明 | 单位 |
|
||||
|------|------|------|
|
||||
| `x` | 左上角 X 坐标 | 英寸 |
|
||||
| `y` | 左上角 Y 坐标 | 英寸 |
|
||||
| `width` | 元素宽度 | 英寸 |
|
||||
| `height` | 元素高度 | 英寸 |
|
||||
|
||||
## 示例
|
||||
|
||||
```yaml
|
||||
# 位置：(1", 2")，尺寸：宽 8"，高 1"
|
||||
box: [1, 2, 8, 1]
|
||||
```
|
||||
|
||||
这表示：
|
||||
- 元素左上角位于 (1", 2")
|
||||
- 元素宽度为 8"
|
||||
- 元素高度为 1"
|
||||
|
||||
## position 属性（表格）
|
||||
|
||||
表格元素使用 `position` 属性指定位置：
|
||||
|
||||
```yaml
|
||||
position: [x, y]
|
||||
```
|
||||
|
||||
| 参数 | 说明 | 单位 |
|
||||
|------|------|------|
|
||||
| `x` | 左上角 X 坐标 | 英寸 |
|
||||
| `y` | 左上角 Y 坐标 | 英寸 |
|
||||
|
||||
## 定位示例
|
||||
|
||||
### 居中文本
|
||||
|
||||
```yaml
|
||||
# 16:9 幻灯片
|
||||
# 宽度 10"，要居中一个 8" 宽的元素
|
||||
# x = (10 - 8) / 2 = 1
|
||||
|
||||
- type: text
|
||||
box: [1, 2, 8, 1]
|
||||
content: "居中文本"
|
||||
font:
|
||||
align: center
|
||||
```
|
||||
|
||||
### 全屏背景
|
||||
|
||||
```yaml
|
||||
# 16:9 幻灯片
|
||||
- type: shape
|
||||
box: [0, 0, 10, 5.625] # 完全覆盖
|
||||
shape: rectangle
|
||||
fill: "#ffffff"
|
||||
```
|
||||
|
||||
### 四个象限
|
||||
|
||||
```yaml
|
||||
slides:
|
||||
- elements:
|
||||
# 左上象限
|
||||
- type: text
|
||||
box: [0.25, 0.25, 4.5, 2.5]
|
||||
content: "左上"
|
||||
|
||||
# 右上象限
|
||||
- type: text
|
||||
box: [5.25, 0.25, 4.5, 2.5]
|
||||
content: "右上"
|
||||
|
||||
# 左下象限
|
||||
- type: text
|
||||
box: [0.25, 3, 4.5, 2.5]
|
||||
content: "左下"
|
||||
|
||||
# 右下象限
|
||||
- type: text
|
||||
box: [5.25, 3, 4.5, 2.5]
|
||||
content: "右下"
|
||||
```
|
||||
|
||||
## 坐标计算
|
||||
|
||||
### 水平居中
|
||||
|
||||
```python
|
||||
x = (slide_width - element_width) / 2
|
||||
```
|
||||
|
||||
### 垂直居中
|
||||
|
||||
```python
|
||||
y = (slide_height - element_height) / 2
|
||||
```
|
||||
|
||||
### 完全居中
|
||||
|
||||
```yaml
|
||||
# 16:9 幻灯片，居中 4" × 2" 的元素
|
||||
# x = (10 - 4) / 2 = 3
|
||||
# y = (5.625 - 2) / 2 = 1.8125
|
||||
|
||||
- type: shape
|
||||
box: [3, 1.8125, 4, 2]
|
||||
shape: rectangle
|
||||
fill: "#3498db"
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 所有坐标和尺寸必须为正数
|
||||
- 元素可以超出页面边界（会发出警告）
|
||||
- 浮点数精度建议保留 2-3 位小数
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [颜色格式](colors.md) - 颜色表示方法
|
||||
|
||||
[返回文档索引](../README.md)
|
||||
191
docs/reference/validation.md
Normal file
191
docs/reference/validation.md
Normal file
@@ -0,0 +1,191 @@
|
||||
# 验证功能
|
||||
|
||||
yaml2pptx 提供强大的验证功能，在转换前自动检查 YAML 文件，提前发现问题。
|
||||
|
||||
## 验证级别
|
||||
|
||||
验证结果分为三个级别：
|
||||
|
||||
### ERROR（错误）
|
||||
|
||||
阻止转换的严重问题：
|
||||
- 文件不存在（图片、模板文件等）
|
||||
- YAML 语法错误
|
||||
- 必需的变量未提供
|
||||
- 无效的数据类型
|
||||
|
||||
### WARNING（警告）
|
||||
|
||||
影响视觉效果但不阻止转换的问题：
|
||||
- 元素超出页面范围
|
||||
- 字体大小过小或过大
|
||||
- 颜色格式不规范但可解析
|
||||
|
||||
### INFO（信息）
|
||||
|
||||
优化建议和提示：
|
||||
- 性能优化建议
|
||||
- 最佳实践提示
|
||||
|
||||
## 验证内容
|
||||
|
||||
### YAML 语法和结构
|
||||
|
||||
- 检查 YAML 语法是否正确
|
||||
- 检查必需字段是否存在
|
||||
- 检查数据类型是否正确
|
||||
|
||||
### 元素边界
|
||||
|
||||
- 检查元素是否超出页面范围
|
||||
- 0.1 英寸容忍度内的超出会发出警告
|
||||
|
||||
### 资源文件
|
||||
|
||||
- 检查图片文件是否存在
|
||||
- 检查模板文件是否存在
|
||||
- 验证文件路径是否有效
|
||||
|
||||
### 颜色格式
|
||||
|
||||
- 检查颜色格式是否正确（#RGB 或 #RRGGBB）
|
||||
- 检查颜色值是否有效
|
||||
|
||||
### 字体配置
|
||||
|
||||
- 检查字体大小是否合理（<6 或 >72 会警告）
|
||||
- 检查字体引用是否存在
|
||||
- 检查字体引用循环
|
||||
|
||||
### 表格数据
|
||||
|
||||
- 检查表格数据一致性
|
||||
- 检查列数是否匹配
|
||||
|
||||
## 使用验证
|
||||
|
||||
### 独立验证
|
||||
|
||||
```bash
|
||||
uv run yaml2pptx.py check presentation.yaml
|
||||
```
|
||||
|
||||
### 使用模板时验证
|
||||
|
||||
```bash
|
||||
uv run yaml2pptx.py check presentation.yaml --template ./templates.yaml
|
||||
```
|
||||
|
||||
### 自动验证
|
||||
|
||||
转换时默认会自动验证：
|
||||
|
||||
```bash
|
||||
uv run yaml2pptx.py convert presentation.yaml output.pptx
|
||||
```
|
||||
|
||||
### 跳过验证
|
||||
|
||||
```bash
|
||||
uv run yaml2pptx.py convert presentation.yaml output.pptx --skip-validation
|
||||
```
|
||||
|
||||
## 验证结果示例
|
||||
|
||||
### 有错误和警告
|
||||
|
||||
```
|
||||
正在检查 YAML 文件...
|
||||
|
||||
- 错误 (2):
|
||||
[幻灯片 2, 元素 1] 无效的颜色格式: red (应为 #RRGGBB)
|
||||
[幻灯片 3, 元素 2] 图片文件不存在: logo.png
|
||||
|
||||
- 警告 (1):
|
||||
[幻灯片 1, 元素 1] 元素右边界超出: 10.50 > 10
|
||||
|
||||
检查完成: 发现 2 个错误, 1 个警告
|
||||
转换已终止
|
||||
```
|
||||
|
||||
### 验证通过
|
||||
|
||||
```
|
||||
正在检查 YAML 文件...
|
||||
|
||||
检查完成: 未发现问题
|
||||
```
|
||||
|
||||
### 仅警告
|
||||
|
||||
```
|
||||
正在检查 YAML 文件...
|
||||
|
||||
- 警告 (2):
|
||||
[幻灯片 1, 元素 1] 元素右边界超出: 10.05 > 10
|
||||
[幻灯片 2, 元素 2] 字体大小过小: 5
|
||||
|
||||
检查完成: 发现 2 个警告
|
||||
```
|
||||
|
||||
## 常见验证错误
|
||||
|
||||
### 文件不存在
|
||||
|
||||
```
|
||||
错误: 图片文件未找到: images/logo.png
|
||||
```
|
||||
|
||||
**解决方法**：检查图片路径是否正确
|
||||
|
||||
### YAML 语法错误
|
||||
|
||||
```
|
||||
错误: YAML 语法错误: 第 15 行
|
||||
```
|
||||
|
||||
**解决方法**：检查缩进和语法，确保 YAML 格式正确
|
||||
|
||||
### 缺少必需变量
|
||||
|
||||
```
|
||||
错误: 缺少必需变量: title
|
||||
```
|
||||
|
||||
**解决方法**：在 `vars` 中提供该变量
|
||||
|
||||
### 无效颜色格式
|
||||
|
||||
```
|
||||
错误: 无效的颜色格式: red (应为 #RRGGBB)
|
||||
```
|
||||
|
||||
**解决方法**：使用 `#ff0000` 格式
|
||||
|
||||
## 验证容忍度
|
||||
|
||||
几何验证时，允许 0.1 英寸的容忍度：
|
||||
|
||||
- 超出 ≤ 0.1 英寸：不报错
|
||||
- 超出 > 0.1 英寸：发出警告
|
||||
|
||||
```python
|
||||
TOLERANCE = 0.1 # 英寸
|
||||
|
||||
if right > slide_width + TOLERANCE:
|
||||
# 报告 WARNING
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
1. **开发时频繁验证**：使用 `check` 命令快速验证
|
||||
2. **修复所有错误**：确保没有 ERROR 级别的问题
|
||||
3. **关注警告**：WARNING 虽不阻止转换，但可能影响视觉效果
|
||||
4. **使用预览模式**：结合预览模式查看实际效果
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [命令行选项](commands.md) - 所有命令和参数
|
||||
- [故障排查](../troubleshooting.md) - 常见问题解决
|
||||
|
||||
[返回文档索引](../README.md)
|
||||
Reference in New Issue
Block a user