readout_program/README.md

读出子系统编程控制模型

📖 在线文档: https://gc-home.top/manual/manual-readout-program.html

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

主要内容

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

项目结构

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

快速开始

构建 HTML 报告

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

# 2. 构建
python 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 的编辑器