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

5.5 KiB
Raw Permalink Blame History

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

项目概述

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

文档即代码约定

目录结构

project.yaml          # 项目元数据与章节列表
build.py              # 构建入口（项目根目录）
chapters/             # Markdown 章节源文件（唯一编辑目标）
assets/               # 图片资源
data/                 # 结构化数据源（CSV/YAML/JSON，通过 @import 引用）
doc_builder/          # Python 构建工具
  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

README 规范

  • README.md 必须包含 CI/CD 状态徽章（指向 Gitea Actions workflow 的 badge URL）
  • README.md 必须包含 在线文档/部署链接，指向文档的实际访问地址
  • 徽章格式: [![Build Status](<gitea_server>/<org>/<repo>/actions/workflows/<workflow>.yml/badge.svg)](<gitea_server>/<org>/<repo>/actions)
  • 部署链接格式: 📖 **在线文档**: [<url>](<url>)

交叉引用

  • 内部引用: 详见 [标题锚点](#标题锚点)
  • 外部引用: [文档名](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 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 / 地址映射）
附录B chapters/81-appendix-troubleshooting.md 故障排查（常见问题、原因分析与排查步骤）

编辑工作流

修改内容 编辑目标 构建方式
正文内容 chapters/*.md python 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 兼容文件