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
│   ├── render_address.py
│   ├── render_registers.py
│   ├── render_requirements.py
│   ├── 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){s=75%}              # 等比例缩放，默认 75%
![alt](../assets/x.png){s=100%}             # 原始尺寸
![alt](../assets/x.png){w=50%}              # 宽度 50%，高度自适应
![alt](../assets/x.png){w=48%, h=200}       # 宽度 48% + 最大高度 200px
```

- `{s=N%}` — 等比例缩放，同时控制宽高
- `{w=N%}` — 仅控制宽度
- `{w=N%, h=M}` — 宽度 + 最大高度（像素）
- 两张图 `{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. 代码块渲染 — ` ```lang `

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

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

### 4. 表格占位符

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

## 构建流程

```
章节 .md 文件
    │
    ├─→ @import 处理器（替换为渲染 HTML）
    ├─→ 代码块渲染器（```schemdraw → SVG）
    └─→ Python-Markdown（→ HTML）
            │
            ├─→ 图片尺寸扩展（{s=N%} / {w=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 |