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 读取它来驱动构建。

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

语法参考

1. 图片

![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 — 导入数据文件

@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

```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 |