readout_program/CLAUDE.md

CLAUDE.md — ez-Q 2.5 读出子系统编程控制模型

项目概述

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

文档即代码约定

目录结构

project.yaml          # 项目元数据与章节列表
chapters/             # Markdown 章节源文件（唯一编辑目标）
assets/               # 图片资源
data/                 # 结构化数据源（CSV/YAML/JSON，通过 @import 引用）
doc_builder/          # Python 构建工具
  build.py            # 构建入口
  templates/          # HTML 模板
  themes/             # CSS 样式
  renderers/          # 自定义渲染器（@import / 代码块渲染）
  processors/         # 数据处理器（供渲染器复用）
  checks/             # 检查脚本（构建时自动运行）
output/               # 构建产物（gitignore）

文件命名规范

• 章节文件: {序号}-{英文slug}.md（如 04-02-acq-codeword.md）
• 子章节用二级编号: {章}-{节}-{slug}.md（如 05-03-exc-wavetable.md）
• 图片文件: 语义化命名（如 readout_ro.png），统一放在 assets/

标题层级

• 每章开头使用 # (H1)
• 节使用 ## (H2)
• 子节使用 ### (H3)
• 禁止在子章节文件中使用 H1，确保拼接后层级正确

图片规范

• 从 chapters/ 引用项目根目录 assets/: ![描述](../assets/xxx.png)
• 此路径同时兼容标准 Markdown 预览和构建时的 base64 内嵌
• 禁止绝对路径（尤其是 Windows 盘符路径如 D:/code/...）
• 构建时自动内嵌为 base64，生成自包含 HTML

交叉引用

• 内部引用: 详见 [标题锚点](#标题锚点)
• 外部引用: [文档名](path/to/doc.md)

非标准 Markdown 扩展

本项目采用 docs-as-code skill 规范的非标准扩展（构建时生效，Markdown 预览中可忽略）：

• @import "../data/file.csv" — 将数据文件或 Markdown 注入当前章节
• @import "../data/file.csv" using render_custom — 使用 doc_builder/renderers/render_custom.py 渲染
• ![描述](../assets/x.png){w=50%} — 图片属性控制（预留）
• 自定义代码块渲染器：doc_builder/renderers/render_<lang>.py

构建流程

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

# 构建 HTML
python doc_builder/build.py

# 输出: output/<标题>.html

文件组织表

章节	文件	内容
§1	chapters/01-changelog.md	修订记录
§2	chapters/02-preface.md	前言（目的、范围、术语等）
§3	chapters/03-overview.md	编程控制模型概述
§4	chapters/04-00-acq-model.md	ACQ 通道编程模型（数据路径）
§4.1	chapters/04-01-acq-downconversion.md	下变频电路配置
§4.2	chapters/04-02-acq-codeword.md	ACQ 码字功能定义
§4.3	chapters/04-03-acq-registers.md	ACQ 寄存器功能定义
§4.4	chapters/04-04-acq-matched-filter.md	匹配滤波器
§4.5	chapters/04-05-acq-data-processing.md	采集数据处理
§4.6	chapters/04-06-acq-pipeline-demo.md	ACQ 全流程控制示例
§5	chapters/05-00-exc-model.md	EXC-Pump 编程模型（数据路径）
§5.1	chapters/05-01-exc-codeword.md	EXC 码字功能定义
§5.2	chapters/05-02-exc-registers.md	寄存器功能定义
§5.3	chapters/05-03-exc-wavetable.md	波形索引表定义
§5.4	chapters/05-04-exc-waveform-store.md	波形仓库定义
§5.5	chapters/05-05-exc-upconversion.md	EXC 上变频电路配置
§5.6	chapters/05-06-pump-config.md	Pump 模拟电路配置
§5.7	chapters/05-07-exc-pipeline-demo.md	EXC-Pump 全流程控制示例
附录A	chapters/80-appendix-ids-table.md	IDS 寄存器索引表（DAQ_REG / AWG_REG / 地址映射）

编辑工作流

修改内容	编辑目标	构建方式
正文内容	chapters/*.md	python doc_builder/build.py
章节顺序	project.yaml → chapters: 列表	同上
图片	assets/	同上（自动内嵌）
结构化数据	data/*.csv / data/*.yaml / data/*.json	同上（通过 @import 注入）
渲染器逻辑	doc_builder/renderers/*.py	同上（自动发现）
数据处理逻辑	doc_builder/processors/*.py	同上（自动发现）
检查规则	doc_builder/checks/*.py	同上（构建时自动运行）
HTML 样式	doc_builder/themes/*.css	同上
HTML 模板	doc_builder/templates/report.html	同上

注意事项

1. 本项目是 硬件寄存器级编程手册，包含大量位域表格和时序说明
2. 平台差异（FPGA vs ASIC）使用代码块标注
3. 数学公式使用 $...$（行内）和 $$...$$（块级）LaTeX 语法，构建时自动保护公式不被 Markdown 转义破坏
4. 编辑以 chapters/ 下的文件为准，项目根目录无旧版 MPE 兼容文件