rbpu_datasheet/readme.md

# RBPU16 读出基带处理芯片 · 数据手册

纯文本管理，Python 构建，生成自包含 HTML 报告。

## 项目结构

```
├── build.ipynb              # 构建入口：VS Code 打开 → Run All
├── project.yaml             # 项目配置（标题、作者、章节列表）
├── chapters/                # 章节源文件（Markdown）
├── data/                    # 结构化数据（CSV / JSON）
├── assets/                  # 图片（PNG / JPG）
├── doc_builder/             # 构建工具（可跨项目复用）
│   ├── themes/datasheet.css
│   ├── renderers/                # 代码块渲染器
│   │   └── schemdraw.py
│   ├── render_table.py           # @import 渲染器：通用表格
│   ├── render_bga.py             # @import 渲染器：BGA 网格
│   ├── render_address.py         # @import 渲染器：地址映射表
│   ├── render_registers.py       # @import 渲染器：寄存器定义
│   ├── render_requirements.py    # @import 渲染器：YAML 需求表
│   ├── import_handler.py         # @import 调度器
│   ├── image_extension.py        # 图片尺寸扩展
│   └── codeblock_extension.py    # 代码块渲染（pre-markdown）
└── output/                  # 构建产物
    └── RBPU16_Data_Sheet.html
```

## project.yaml

每个项目根目录的配置文件，`build.ipynb` 读取它来驱动构建。

```yaml
title: RBPU16 读出基带处理芯片
subtitle: 数据手册
author: 郭成
theme: datasheet
chapters:
  - 00_cover.md
  - 01_specifications.md
  - ...
```

## 语法参考

### 1. 图片

```markdown
![alt](../assets/x.png)                     # 默认 80% 宽，高自动等比
![alt](../assets/x.png){w=50%}              # 宽 50%，高自动等比
![alt](../assets/x.png){h=50%}              # 高 50%，宽自动等比
![alt](../assets/x.png){w=50%, h=300}       # 宽 50% + 最大高度 300px
```

- `{w=N%}` — 宽 N%，高自动等比
- `{h=N%}` — 高 N%，宽自动等比
- `{w=N%, h=M}` — 同时指定宽高（h 为像素时限制最大高度）
- 不写 → 默认 `w=80%`
- 两张图 `{w=N%}` 相加 ≤ 100% 时自动并排

### 2. `@import` — 导入数据文件

```markdown
@import "data/file.csv"                               # 无 using → 行号代码视图
@import "data/file.csv" using render_table.py         # 通用表格
@import "data/pin_loc.csv" using render_bga.py        # BGA 焊球网格
@import "data/ids.json" using render_registers.py     # 寄存器定义表
```

`using <script.py>` 加载项目根目录下的 Python 脚本，调用 `render(filepath)` → HTML。脚本不存在时降级为行号视图，不报错。

### 3. 代码块渲染

```schemdraw
import schemdraw
from schemdraw import elements as e
with schemdraw.Drawing(show=False) as d:
    d += e.Resistor().right().label('R1')
```

构建时在 markdown 之前执行：代码块 → `doc_builder/renderers/<tag>.py` → SVG/HTML。`mermaid` 等标签为 passthrough（浏览器端渲染）。

### 4. 占位符

表格中 `—` 表示待补充数据。

## 构建流程

```
章节 .md 文件
    │
    ├─→ @import 处理器（替换为渲染 HTML）
    ├─→ 代码块渲染器（```lang → 渲染输出）
    └─→ Python-Markdown（→ HTML）
            │
            ├─→ 图片尺寸扩展（{w=N%} / {h=N%}）
            └─→ codehilite（代码高亮）
    │
    ▼
组装 HTML（封面 + 章节 + 修订历史）
    │
    ▼
图片 base64 内嵌 → 自包含单文件
```

## 编辑指南

| 修改内容 | 编辑 | 重建 |
|---------|------|------|
| 正文 | `chapters/*.md` | Run All |
| 管脚 | `data/pin_name.csv` | Run All |
| 寄存器 | `script/读出子系统IDS表.xls` | ids_import.ipynb → Run All |
| 样式 | `doc_builder/themes/datasheet.css` | Run All |
| 配置 | `project.yaml` | Run All |