116 lines
5.4 KiB
Markdown
116 lines
5.4 KiB
Markdown
# 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/**: ``
|
||
- 此路径同时兼容标准 Markdown 预览和构建时的 base64 内嵌
|
||
- **禁止绝对路径**（尤其是 Windows 盘符路径如 `D:/code/...`）
|
||
- 构建时自动内嵌为 base64，生成自包含 HTML
|
||
|
||
### README 规范
|
||
- README.md 必须包含 **CI/CD 状态徽章**（指向 Gitea Actions workflow 的 badge URL）
|
||
- README.md 必须包含 **在线文档/部署链接**，指向文档的实际访问地址
|
||
- 徽章格式: `[](<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` 渲染
|
||
- `{w=50%}` — 图片属性控制（预留）
|
||
- 自定义代码块渲染器：`doc_builder/renderers/render_<lang>.py`
|
||
|
||
## 构建流程
|
||
|
||
```bash
|
||
# 安装依赖（首次）
|
||
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 / 地址映射） |
|
||
|
||
## 编辑工作流
|
||
|
||
| 修改内容 | 编辑目标 | 构建方式 |
|
||
|:---|:---|:---|
|
||
| 正文内容 | `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 兼容文件
|