116 lines
3.6 KiB
Markdown
116 lines
3.6 KiB
Markdown
# 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
|
||
{s=75%} # 等比例缩放，默认 75%
|
||
{s=100%} # 原始尺寸
|
||
{w=50%} # 宽度 50%，高度自适应
|
||
{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 |
|