readout
/
readout_program
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
readout_program/CLAUDE.md

3.9 KiB
Raw Blame History

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

项目概述

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

文档即代码约定

目录结构

project.yaml          # 项目元数据与章节列表
chapters/             # Markdown 章节源文件（唯一编辑目标）
assets/               # 图片资源
doc_builder/          # Python 构建工具
  build.py            # 构建入口
  templates/          # HTML 模板
  themes/             # CSS 样式
output/               # 构建产物（gitignore）

文件命名规范

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

标题层级

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

图片规范

  • 一律使用项目根目录相对路径: ![描述](./assets/xxx.png)
  • 禁止绝对路径（尤其是 Windows 盘符路径如 D:/code/...）
  • 构建时自动内嵌为 base64，生成自包含 HTML

交叉引用

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

非标准 Markdown 扩展

本项目采用 docs-as-code skill 规范的非标准扩展：

  • @import "data/file.csv" — 数据注入（预留）
  • ![描述](path){w=50%} — 图片属性控制（预留）
  • 自定义代码块渲染器（预留 doc_builder/renderers/）

构建流程

# 安装依赖（首次）
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-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 采集数据处理
§5 chapters/05-exct-model.md EXCT-Pump 编程模型（数据路径）
§5.1 chapters/05-01-exct-codeword.md EXCT 码字功能定义
§5.2 chapters/05-02-exct-registers.md 寄存器功能定义
§5.3 chapters/05-03-exct-wavetable.md 波形索引表定义
§5.4 chapters/05-04-exct-waveform-store.md 波形仓库定义
§5.5 chapters/05-05-exct-upconversion.md EXCT 上变频电路配置
§5.6 chapters/05-06-pump-config.md Pump 模拟电路配置

编辑工作流

修改内容 编辑目标 构建方式
正文内容 chapters/*.md python doc_builder/build.py
章节顺序 project.yaml → chapters: 列表 同上
图片 assets/ 同上（自动内嵌）
HTML 样式 doc_builder/themes/*.css 同上
HTML 模板 doc_builder/templates/report.html 同上

注意事项

  1. 本项目是 硬件寄存器级编程手册，包含大量位域表格和时序说明
  2. 平台差异（FPGA vs ASIC）使用代码块标注
  3. 数学公式使用 $...$（行内）和 $$...$$（块级）LaTeX 语法
  4. 原有根目录下的 *.md 文件是 MPE 编辑器兼容的历史文件，编辑以 chapters/ 为准