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

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

语法参考

1. 图片

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

@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. 代码块渲染

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