readout_program/README.md

# 读出子系统编程控制模型

本项目为 ez-Q 2.5 读出子系统的编程控制模型文档。采用 **"文档即代码" (Docs as Code)** 工作方式，
通过 Markdown 纯文本写作、Git 版本控制和 Python 构建管道生成自包含 HTML 报告。

**主要内容**

- RI 通道编程（激励生成发送）
- RO 通道编程（回波采集处理）
- Pump 通道编程（泵浦信号控制）

## 项目结构

```
project.yaml          # 项目配置（标题、作者、版本、章节列表）
chapters/             # Markdown 章节源文件
assets/               # 图片资源
data/                 # 结构化数据源（CSV/YAML/JSON，通过 @import 引用）
doc_builder/          # Python 构建工具
  build.py            # 构建入口
  templates/          # HTML 模板（含 A4 封面）
  themes/             # CSS 样式（屏幕 + 打印）
  renderers/          # 自定义渲染器（@import / 代码块）
  processors/         # 数据处理器
  checks/             # 检查脚本
output/               # 构建产物（.gitignore）
```

## 快速开始

### 构建 HTML 报告

```bash
# 1. 安装依赖（首次）
pip install -r requirements.txt

# 2. 构建
python doc_builder/build.py

# 3. 打开 output/<标题>.html 即可浏览
```

### 编辑文档

- 修改 `chapters/` 下的 `.md` 文件
- 添加/删除/重新排序章节：编辑 `project.yaml` 的 `chapters` 列表
- 修改样式：编辑 `doc_builder/themes/report.css`
- 修改页面布局：编辑 `doc_builder/templates/report.html`
- 图片放在 `assets/` 目录，章节中通过 `../assets/xxx.png` 引用

### 非标准 Markdown 扩展

本项目支持以下扩展语法（仅在构建时生效）：

- **`@import "path"`** — 将数据文件或 Markdown 注入当前章节
- **`@import "path" using render_xxx`** — 使用自定义渲染器
- **`![alt](../assets/x.png){w=50%}`** — 图片属性控制

### 编辑器推荐

- VS Code + Markdown 预览
- Typora
- Obsidian
- 任何支持 Markdown 的编辑器