readout
/
rbpu_datasheet
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

修正封面和格式

This commit is contained in:
guocheng 2026-07-19 21:40:24 +08:00
parent 9a33df9c42
commit eccfd5ce43
5 changed files with 208 additions and 268 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
build.ipynb
View File

@ -73,13 +73,47 @@
" chapters.append(dict(id=f'app{lb}',number=f'Appendix {lb}',title=mx.group(1) if mx else fp.stem,content=c))\n", " chapters.append(dict(id=f'app{lb}',number=f'Appendix {lb}',title=mx.group(1) if mx else fp.stem,content=c))\n",
"\n", "\n",
"CSS=(B/'doc_builder'/'themes'/'datasheet.css').read_text(encoding='utf-8')\n", "CSS=(B/'doc_builder'/'themes'/'datasheet.css').read_text(encoding='utf-8')\n",
"TITLE='RBPU16'; AU='Guo Cheng'; DATE=dt.now().strftime('%Y-%m-%d')\n", "\n",
"def _parse_yaml(path):\n",
" meta={}; features=[]; in_features=False\n",
" with open(path,encoding='utf-8') as f:\n",
" for line in f:\n",
" s=line.strip(); k=None\n",
" if s.startswith('features:'):\n",
" in_features=True; continue\n",
" if in_features:\n",
" if s.startswith('- '):\n",
" features.append(s[2:].strip()); continue\n",
" elif s and not line.startswith(' '):\n",
" in_features=False\n",
" if not in_features and ':' in s:\n",
" k,v=s.split(':',1)\n",
" meta[k.strip()]=v.strip()\n",
" meta['features']=features\n",
" return meta\n",
"\n",
"meta=_parse_yaml(B/'project.yaml')\n",
"TITLE=meta.get('title','RBPU16')\n",
"SUBTITLE=meta.get('subtitle','数据手册')\n",
"AUTHOR=meta.get('author','郭成')\n",
"AU=AUTHOR\n",
"DATE=dt.now().strftime('%Y-%m-%d')\n",
"\n",
"def _title_html(t):\n",
" parts=t.split(' ',1)\n",
" if len(parts)>1:\n",
" return f'<span class=\"model\">{eh(parts[0])}</span> <span class=\"zh-name\">{eh(parts[1])}</span>'\n",
" return eh(t)\n",
"_title=_title_html(TITLE)\n",
"\n",
"COVER=''.join([\n", "COVER=''.join([\n",
" '<div class=\"cover-page\">',\n", " '<div class=\"cover-page\">',\n",
" '<div class=\"product-family\">READOUT BASEBAND PROCESSOR</div>',\n", " '<div class=\"cover-top\"><div class=\"product-family\">READOUT BASEBAND PROCESSOR</div></div>',\n",
" '<h1>RBPU16<br>',chr(35835),chr(20986),chr(22522),chr(24102),chr(22788),chr(29702),chr(33455),chr(29255),'</h1>',\n", " '<div class=\"cover-body\">',\n",
" '<div class=\"subtitle\">Data Sheet &middot; User Manual</div>',\n", " f'<h1>{_title}</h1>',\n",
" f'<div class=\"cover-meta\"><p>Rev 1.0 &middot; {DATE}</p><p>{AU}</p></div>',\n", " f'<div class=\"subtitle\">{eh(SUBTITLE)}</div>',\n",
" '</div>',\n",
" f'<div class=\"cover-bottom\"><span class=\"rev\">Rev 1.0 &middot; {DATE}</span><span class=\"author\">{eh(AUTHOR)}</span></div>',\n",
" '</div>',\n", " '</div>',\n",
"])\n", "])\n",
"ch_html=chr(10).join(f'<div class=\"chapter\" id=\"{c[\"id\"]}\">{c[\"content\"]}</div>' for c in chapters)\n", "ch_html=chr(10).join(f'<div class=\"chapter\" id=\"{c[\"id\"]}\">{c[\"content\"]}</div>' for c in chapters)\n",

2
chapters/00_cover.md
View File

@ -16,4 +16,4 @@ RBPU16 是一款面向超导量子比特态信息读出的 SoC 芯片，最大
## 功能框图 ## 功能框图
![系统框图](../assets/chip_schematic.png){s=100%} ![系统框图](../assets/chip_schematic.png){w=100%}

41
doc_builder/image_extension.py
View File

@ -1,10 +1,10 @@
"""Python-Markdown extension: image sizing. """Python-Markdown extension: image sizing.
Syntax (standard Markdown paths, relative to chapter file): Syntax:
![alt](../assets/x.png){s=50%} → scale to 50% (width, auto height) ![alt](../assets/x.png){w=50%} → width 50%, height auto (proportional)
![alt](../assets/x.png){w=50%} → width 50%, auto height ![alt](../assets/x.png){h=50%} → height 50%, width auto (proportional)
![alt](../assets/x.png){w=50%, h=300} → width 50%, max-height 300px ![alt](../assets/x.png){w=50%, h=300} → width 50%, max-height 300px (pixel h)
![alt](../assets/x.png) → default: s=75% ![alt](../assets/x.png) → default: width 80%, height auto
""" """
import re import re
from markdown.extensions import Extension from markdown.extensions import Extension
@ -13,11 +13,10 @@ from markdown.inlinepatterns import ImageInlineProcessor
IMG_RE = ( IMG_RE = (
r'\!\[(?P<alt>.*?)\]\((?P<src>[^)]+)\)' r'\!\[(?P<alt>.*?)\]\((?P<src>[^)]+)\)'
r'(?:\{' r'(?:\{'
r'(?:s=(?P<s>\d+%))?'
r'(?:,\s*)?'
r'(?:w=(?P<w>\d+%))?' r'(?:w=(?P<w>\d+%))?'
r'(?:,\s*h=(?P<h>\d+)(?:px)?)?' r'(?:,\s*)?'
r'\}?)?' r'(?:h=(?P<h>\d+)(?:%|px)?)?'
r'\})?'
) )
@ -26,22 +25,24 @@ class SizedImageProcessor(ImageInlineProcessor):
def handleMatch(self, m, data): def handleMatch(self, m, data):
alt = m.group('alt') alt = m.group('alt')
src = m.group('src') src = m.group('src')
scale = m.group('s') w = m.group('w')
width = m.group('w') h = m.group('h')
height = m.group('h')
# Normalize paths for HTML output
src = src.replace('../assets/', 'assets/') src = src.replace('../assets/', 'assets/')
src = src.replace('../circuits/output/', 'assets/') src = src.replace('../circuits/output/', 'assets/')
if scale: if w and h:
style = f'width:{scale}; height:auto; max-width:none; max-height:none' # Both specified: h could be % or px
elif width: style = f'width:{w}; height:{h}; max-width:none; max-height:none'
style = f'width:{width}; max-width:none' elif w:
if height: # w only: auto height (proportional)
style += f'; max-height:{height}px' style = f'width:{w}; height:auto; max-width:none; max-height:none'
elif h:
# h only: auto width (proportional)
style = f'height:{h}; width:auto; max-width:none; max-height:none'
else: else:
style = 'width:75%; height:auto' # Default: 80%
style = 'width:80%; height:auto; max-width:none; max-height:none'
img_tag = f'<img src="{src}" alt="{alt}" style="{style}">' img_tag = f'<img src="{src}" alt="{alt}" style="{style}">'
el = self.md.htmlStash.store(img_tag) el = self.md.htmlStash.store(img_tag)

328
doc_builder/themes/datasheet.css
View File

@ -1,28 +1,25 @@
/* ============================================================ /* ============================================================
Datasheet Theme — 芯片数据手册风格 Datasheet Theme
============================================================ */ ============================================================ */
:root { :root {
--bg: #fff; --bg: #fff;
--text: #1a1a1a; --text: #000;
--text-muted: #555; --text-muted: #333;
--heading: #000; --heading: #000;
--accent: #003d7c; --accent: #003d7c;
--accent-light: #e8f0f8; --th-bg: #f2f2f2;
--th-bg: #e9ecf0; --th-border: #ccc;
--th-border: #c0c4c8; --stripe: #fafafa;
--stripe: #f7f8f9; --link: #000;
--cover-bg: #003d7c; --note-bg: #f7f7f7;
--cover-text: #fff; --note-border: #999;
--link: #005da0;
--note-bg: #f5f7fa;
--note-border: #003d7c;
--font-body: "Noto Serif CJK SC", "Source Han Serif SC", "SimSun", Georgia, serif; --font-body: "Noto Serif CJK SC", "Source Han Serif SC", "SimSun", Georgia, serif;
--font-heading: "Noto Sans CJK SC", "Source Han Sans SC", "Microsoft YaHei", "PingFang SC", sans-serif; --font-heading: "Noto Sans CJK SC", "Source Han Sans SC", "Microsoft YaHei", "PingFang SC", sans-serif;
--font-mono: "Cascadia Code", "Fira Code", Consolas, monospace; --font-mono: "Cascadia Code", "Fira Code", Consolas, monospace;
--size: 14px; --size: 16px;
--line: 1.7; --line: 1.75;
} }
*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; } *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
@ -42,70 +39,73 @@ body {
/* ---------- Cover ---------- */ /* ---------- Cover ---------- */
.cover-page { .cover-page {
width: 100%;
box-sizing: border-box;
padding: 0 2.5em;
margin: 0 0 3em 0;
min-height: 100vh; min-height: 100vh;
display: flex;
flex-direction: column;
justify-content: center;
align-items: center;
padding: 4em 2.5em;
margin: 0 0 3em 0;
position: relative; position: relative;
}
.cover-page-inner {
position: absolute;
top: 50%; left: 50%;
transform: translate(-50%, -50%);
text-align: center;
width: 100%;
padding: 0 2.5em;
box-sizing: border-box;
}
.cover-page .cover-meta {
position: absolute;
bottom: 40px;
left: 0; right: 0;
font-size: 0.8rem;
color: var(--text-muted);
text-align: center; text-align: center;
} }
.cover-page::after {
content: ''; .cover-top { margin-bottom: 4em; }
position: absolute;
bottom: 0; left: 50%; transform: translateX(-50%); .cover-top .product-family {
width: 60px; height: 1px;
background: var(--th-border);
}
.cover-page .product-family {
font-family: var(--font-heading); font-family: var(--font-heading);
font-size: 0.75rem; font-size: 0.8rem;
letter-spacing: 0.5em; letter-spacing: 0.5em;
text-transform: uppercase; text-transform: uppercase;
color: var(--text-muted); color: var(--text-muted);
margin-bottom: 64px;
}
.cover-page h1 {
font-family: var(--font-heading);
font-size: 2.4rem;
font-weight: 700; font-weight: 700;
line-height: 1.4; }
margin-bottom: 20px;
.cover-body { max-width: 100%; }
.cover-body h1 {
font-family: var(--font-heading);
font-size: 2.6rem;
font-weight: 700;
line-height: 1.3;
margin-bottom: 0.5em;
color: var(--heading); color: var(--heading);
border: none; border: none;
padding: 0; padding: 0;
} }
.cover-page .subtitle {
.cover-body h1 .model { font-weight: 800; display: inline; }
.cover-body h1 .zh-name {
font-weight: 600;
color: var(--text-muted);
display: inline;
}
.cover-body .subtitle {
font-family: var(--font-heading); font-family: var(--font-heading);
font-size: 1rem; font-size: 1.05rem;
font-weight: 400; font-weight: 400;
color: var(--text-muted); color: var(--text-muted);
margin-bottom: 64px; letter-spacing: 0.1em;
} }
.cover-page .feature-list { display: none; }
.cover-page .cover-meta { .cover-bottom {
position: absolute; position: absolute;
bottom: 40px; bottom: 3.5em;
font-size: 0.8rem; left: 0; right: 0;
font-size: 0.85rem;
color: var(--text-muted); color: var(--text-muted);
font-family: var(--font-heading);
display: flex;
flex-direction: column;
justify-content: center;
align-items: center;
gap: 0.2em;
} }
.cover-page .cover-meta p { margin: 4px 0; }
.cover-bottom .rev { font-weight: 700; color: var(--heading); }
.cover-bottom .author { white-space: nowrap; }
/* ---------- Chapters ---------- */ /* ---------- Chapters ---------- */
.chapter { padding: 2em 2.5em; } .chapter { padding: 2em 2.5em; }
@ -113,43 +113,44 @@ body {
/* ---------- Headings ---------- */ /* ---------- Headings ---------- */
h1 { h1 {
font-family: var(--font-heading); font-family: var(--font-heading);
font-size: 1.5rem; font-size: 1.6rem;
font-weight: 700; font-weight: 800;
color: var(--heading); color: var(--heading);
margin: 2em 0 0.8em; margin: 2em 0 0.8em;
padding-bottom: 6px; padding-bottom: 8px;
border-bottom: 2px solid var(--accent); border-bottom: 2px solid var(--heading);
} }
h2 { h2 {
font-family: var(--font-heading); font-family: var(--font-heading);
font-size: 1.25rem; font-size: 1.3rem;
font-weight: 700; font-weight: 700;
color: var(--accent); color: var(--heading);
margin: 1.5em 0 0.6em; margin: 1.5em 0 0.6em;
padding-bottom: 4px; padding-bottom: 4px;
border-bottom: 1px solid var(--th-border); border-bottom: 1px solid var(--th-border);
} }
h3 { h3 {
font-family: var(--font-heading); font-family: var(--font-heading);
font-size: 1.1rem; font-size: 1.15rem;
font-weight: 600; font-weight: 700;
color: var(--heading); color: var(--heading);
margin: 1.2em 0 0.5em; margin: 1.2em 0 0.5em;
} }
h4 { h4 {
font-family: var(--font-heading); font-family: var(--font-heading);
font-size: 1rem; font-size: 1.05rem;
font-weight: 600; font-weight: 700;
color: var(--text); color: var(--text);
margin: 1em 0 0.4em; margin: 1em 0 0.4em;
} }
/* ---------- Body ---------- */ /* ---------- Body ---------- */
p { margin: 0.6em 0; text-align: justify; } p { margin: 0.6em 0; text-align: justify; color: var(--text); }
ul, ol { margin: 0.6em 0; padding-left: 2em; } ul, ol { margin: 0.6em 0; padding-left: 2em; color: var(--text); }
li { margin: 2px 0; } li { margin: 2px 0; }
a { color: var(--link); text-decoration: none; } a { color: var(--link); text-decoration: none; }
a:hover { text-decoration: underline; } a:hover { text-decoration: underline; }
strong { font-weight: 700; color: var(--heading); }
/* ---------- Tables ---------- */ /* ---------- Tables ---------- */
table { table {
@ -161,13 +162,14 @@ table {
thead th { thead th {
background-color: var(--th-bg); background-color: var(--th-bg);
font-family: var(--font-heading); font-family: var(--font-heading);
font-weight: 600; font-weight: 700;
font-size: 0.88rem; font-size: 0.88rem;
text-align: left; text-align: left;
padding: 6px 10px; padding: 6px 10px;
border: 1px solid var(--th-border); border: 1px solid var(--th-border);
border-bottom: 2px solid var(--accent); border-bottom: 2px solid var(--heading);
white-space: nowrap; white-space: nowrap;
color: var(--heading);
} }
tbody td { tbody td {
padding: 5px 10px; padding: 5px 10px;
@ -175,16 +177,15 @@ tbody td {
vertical-align: top; vertical-align: top;
} }
tbody tr:nth-child(even) { background-color: var(--stripe); } tbody tr:nth-child(even) { background-color: var(--stripe); }
table.compact { font-size: 0.82rem; } table.compact { font-size: 0.85rem; }
table.compact thead th { font-size: 0.8rem; padding: 3px 7px; } table.compact thead th { font-size: 0.82rem; padding: 3px 7px; }
table.compact tbody td { padding: 3px 7px; } table.compact tbody td { padding: 3px 7px; }
td.addr, td.bits, td.reset-val { font-family: var(--font-mono); font-size: 0.85em; white-space: nowrap; } td.addr, td.bits, td.reset-val { font-family: var(--font-mono); font-size: 0.85em; white-space: nowrap; }
td.bits { text-align: center; } td.bits { text-align: center; }
/* Permissions */ .perm-rw { color: var(--text); font-weight: 700; }
.perm-rw { color: #1a7a1a; font-weight: 600; } .perm-ro { color: var(--text); font-weight: 700; }
.perm-ro { color: #b8860b; font-weight: 600; } .perm-wc { color: var(--text); font-weight: 700; }
.perm-wc { color: #8b0000; font-weight: 600; }
/* ---------- Code ---------- */ /* ---------- Code ---------- */
code { code {
@ -194,172 +195,77 @@ code {
padding: 1px 5px; padding: 1px 5px;
border-radius: 2px; border-radius: 2px;
border: 1px solid var(--th-border); border: 1px solid var(--th-border);
color: var(--text);
} }
pre { pre {
font-family: var(--font-mono); font-family: var(--font-mono);
font-size: 0.82rem; font-size: 0.85rem;
background: var(--note-bg); background: var(--note-bg);
border: 1px solid var(--th-border); border: 1px solid var(--th-border);
border-left: 3px solid var(--accent); border-left: 3px solid var(--heading);
padding: 12px; padding: 12px;
margin: 1em 0; margin: 1em 0;
overflow-x: auto; overflow-x: auto;
line-height: 1.5; line-height: 1.5;
color: var(--text);
} }
pre code { background: none; padding: 0; border: none; font-size: inherit; } pre code { background: none; padding: 0; border: none; font-size: inherit; }
/* Code block with line numbers (default @import display) */
.code-block { .code-block {
margin: 1em 0; margin: 1em 0;
border: 1px solid var(--th-border); border: 1px solid var(--th-border);
border-radius: 3px;
overflow: hidden; overflow: hidden;
} }
.code-header { .code-header {
background: var(--th-bg); background: var(--th-bg);
font-family: var(--font-heading); font-family: var(--font-heading);
font-size: 0.78rem; font-size: 0.8rem;
padding: 4px 10px; padding: 4px 10px;
color: var(--text-muted); color: var(--text-muted);
border-bottom: 1px solid var(--th-border); border-bottom: 1px solid var(--th-border);
font-weight: 700;
} }
.code-lines { .code-lines {
margin: 0; margin: 0; border: none; border-left: none;
border: none; font-size: 0.82rem; line-height: 1.55;
border-left: none; padding: 8px 0; background: var(--stripe);
font-size: 0.78rem; color: var(--text);
line-height: 1.55;
padding: 8px 0;
background: #fafbfc;
} }
.code-lines .ln { .code-lines .ln {
display: inline-block; display: inline-block; width: 40px;
width: 40px; text-align: right; color: var(--text-muted);
text-align: right; user-select: none; padding-right: 12px;
color: var(--text-muted); margin-right: 8px; border-right: 1px solid var(--th-border);
user-select: none;
padding-right: 12px;
margin-right: 8px;
border-right: 1px solid var(--th-border);
} }
.code-lines .lc { .code-lines .lc { color: var(--text); }
/* ---------- Figures ---------- */
figure { margin: 1.2em auto; text-align: center; max-width: 75%; }
figure img { max-width: 100%; max-height: 420px; height: auto; border-radius: 2px; }
figure figcaption {
font-family: var(--font-heading); font-size: 0.85rem;
color: var(--text-muted); margin-top: 4px; font-weight: 700;
}
p img { max-width: 75%; max-height: 400px; height: auto; display: block; margin: 0.8em auto; border-radius: 2px; }
td img { max-width: 100%; max-height: 180px; margin: 0; }
.img-row { display: flex; gap: 1em; justify-content: center; align-items: flex-start; margin: 1em 0; }
.img-row img { flex: 0 0 auto; margin: 0; border-radius: 2px; }
/* ---------- Notes ---------- */
blockquote {
margin: 1em 0; padding: 10px 16px;
border-left: 3px solid var(--heading);
background: var(--note-bg); font-size: 0.92rem;
color: var(--text); color: var(--text);
} }
/* ---------- Figures ---------- */
figure {
margin: 1.2em auto;
text-align: center;
max-width: 75%;
}
figure img {
max-width: 100%;
max-height: 420px;
height: auto;
border-radius: 3px;
}
figure figcaption {
font-family: var(--font-heading);
font-size: 0.85rem;
color: var(--text-muted);
margin-top: 4px;
}
/* Standalone images (not in figure) */
p img {
max-width: 75%;
max-height: 400px;
height: auto;
display: block;
margin: 0.8em auto;
border-radius: 3px;
}
/* Small images: inline icons, small diagrams */
img.img-sm, figure.img-sm { max-width: 40%; }
figure.img-sm img { max-height: 240px; }
/* Full-width: detailed block diagrams that need detail */
img.img-lg, figure.img-lg { max-width: 95%; }
figure.img-lg img { max-height: 600px; }
/* Images inside table cells — tighter constraints */
td img {
max-width: 100%;
max-height: 180px;
margin: 0;
}
/* Side-by-side image row */
.img-row {
display: flex;
gap: 1em;
justify-content: center;
align-items: flex-start;
margin: 1em 0;
}
.img-row img {
flex: 0 0 auto;
margin: 0;
border-radius: 3px;
}
/* ---------- Blockquote / Notes ---------- */
blockquote {
margin: 1em 0;
padding: 10px 16px;
border-left: 4px solid var(--note-border);
background: var(--note-bg);
font-size: 0.92rem;
}
/* ---------- TOC ---------- */
.toc { margin-bottom: 2em; }
.toc h2 { font-size: 1.4rem; border-bottom: 2px solid var(--accent); }
.toc-list { list-style: none; padding: 0; }
.toc-list li {
padding: 4px 0;
border-bottom: 1px dotted var(--th-border);
display: flex;
justify-content: space-between;
}
.toc-list li a { flex: 1; }
/* ---------- Sidebar (screen only) ---------- */
@media screen and (min-width: 1200px) {
body { padding-left: 260px; max-width: 1100px; }
.screen-toc {
position: fixed;
left: max(0px, calc((100vw - 1100px) / 2 - 240px));
top: 0;
width: 220px;
height: 100vh;
overflow-y: auto;
background: var(--note-bg);
border-right: 1px solid var(--th-border);
padding: 16px 12px;
font-size: 0.78rem;
z-index: 100;
}
.cover-page { margin-left: calc(-2em - 260px + 2.5em); }
}
@media screen and (max-width: 1199px) {
.screen-toc { display: none; }
}
.screen-toc ul { list-style: none; padding: 0; }
.screen-toc li { margin: 3px 0; line-height: 1.4; }
.screen-toc a { color: var(--text); display: block; padding: 2px 5px; border-radius: 2px; }
.screen-toc a:hover { background: var(--accent-light); text-decoration: none; }
/* ---------- Register summary ---------- */
.reg-summary { font-size: 0.9rem; } .reg-summary { font-size: 0.9rem; }
.reg-summary strong { margin-right: 4px; } .reg-summary strong { margin-right: 4px; }
.reg-summary code { margin-right: 12px; } .reg-summary code { margin-right: 12px; }
/* ---------- Warning ---------- */
.warning { .warning {
background: #fff3cd; background: #f5f5f5; border: 1px solid #999;
border: 1px solid #ffc107; padding: 10px; margin: 10px 0; color: var(--text);
padding: 10px;
margin: 10px 0;
border-radius: 3px;
} }
/* ---------- Utility ---------- */ /* ---------- Utility ---------- */
@ -370,8 +276,8 @@ blockquote {
/* ---------- Auto-numbering ---------- */ /* ---------- Auto-numbering ---------- */
body.auto-numbering { counter-reset: section; } body.auto-numbering { counter-reset: section; }
body.auto-numbering .chapter h1 { counter-increment: section; counter-reset: subsection; } body.auto-numbering .chapter h1 { counter-increment: section; counter-reset: subsection; }
body.auto-numbering .chapter h1::before { content: counter(section) ". "; } body.auto-numbering .chapter h1::before { content: counter(section) ". "; font-weight: 800; }
body.auto-numbering .chapter h2 { counter-increment: subsection; counter-reset: subsubsection; } body.auto-numbering .chapter h2 { counter-increment: subsection; counter-reset: subsubsection; }
body.auto-numbering .chapter h2::before { content: counter(section) "." counter(subsection) " "; } body.auto-numbering .chapter h2::before { content: counter(section) "." counter(subsection) " "; font-weight: 700; }
body.auto-numbering .chapter h3 { counter-increment: subsubsection; } body.auto-numbering .chapter h3 { counter-increment: subsubsection; }
body.auto-numbering .chapter h3::before { content: counter(section) "." counter(subsection) "." counter(subsubsection) " "; } body.auto-numbering .chapter h3::before { content: counter(section) "." counter(subsection) "." counter(subsubsection) " "; font-weight: 700; }

61
readme.md
View File

@ -1,28 +1,28 @@
# RBPU16 读出基带处理芯片 · 数据手册 # RBPU16 读出基带处理芯片 · 数据手册
纯文本管理，Python 脚本构建，生成自包含 HTML 报告。 纯文本管理，Python 构建，生成自包含 HTML 报告。
## 项目结构 ## 项目结构
``` ```
├── build.ipynb # 构建入口：VS Code 打开 → Run All ├── build.ipynb # 构建入口：VS Code 打开 → Run All
├── project.yaml # 项目配置（标题、作者、章节列表） ├── project.yaml # 项目配置（标题、作者、章节列表）
├── chapters/ # 章节源文件（Markdown） ├── chapters/ # 章节源文件（Markdown）
├── data/ # 结构化数据（CSV / JSON） ├── data/ # 结构化数据（CSV / JSON）
├── assets/ # 图片（PNG / JPG） ├── assets/ # 图片（PNG / JPG）
├── doc_builder/ # 构建工具（可跨项目复用） ├── doc_builder/ # 构建工具（可跨项目复用）
│ ├── themes/datasheet.css │ ├── themes/datasheet.css
│ ├── renderers/ # 代码块渲染器 │ ├── renderers/ # 代码块渲染器
│ │ └── schemdraw.py │ │ └── schemdraw.py
│ ├── render_table.py # @import 渲染器 │ ├── render_table.py # @import 渲染器：通用表格
│ ├── render_bga.py │ ├── render_bga.py # @import 渲染器：BGA 网格
│ ├── render_address.py │ ├── render_address.py # @import 渲染器：地址映射表
│ ├── render_registers.py │ ├── render_registers.py # @import 渲染器：寄存器定义
│ ├── render_requirements.py │ ├── render_requirements.py # @import 渲染器：YAML 需求表
│ ├── import_handler.py # @import 调度器 │ ├── import_handler.py # @import 调度器
│ ├── image_extension.py # 图片尺寸扩展 │ ├── image_extension.py # 图片尺寸扩展
│ └── codeblock_extension.py# 代码块渲染（pre-markdown） │ └── codeblock_extension.py # 代码块渲染（pre-markdown）
└── output/ # 构建产物 └── output/ # 构建产物
└── RBPU16_Data_Sheet.html └── RBPU16_Data_Sheet.html
``` ```
@ -46,15 +46,16 @@ chapters:
### 1. 图片 ### 1. 图片
```markdown ```markdown
![alt](../assets/x.png){s=75%} # 等比例缩放，默认 75% ![alt](../assets/x.png) # 默认 80% 宽，高自动等比
![alt](../assets/x.png){s=100%} # 原始尺寸 ![alt](../assets/x.png){w=50%} # 宽 50%，高自动等比
![alt](../assets/x.png){w=50%} # 宽度 50%，高度自适应 ![alt](../assets/x.png){h=50%} # 高 50%，宽自动等比
![alt](../assets/x.png){w=48%, h=200} # 宽度 48% + 最大高度 200px ![alt](../assets/x.png){w=50%, h=300} # 宽 50% + 最大高度 300px
``` ```
- `{s=N%}` — 等比例缩放，同时控制宽高 - `{w=N%}` — 宽 N%，高自动等比
- `{w=N%}` — 仅控制宽度 - `{h=N%}` — 高 N%，宽自动等比
- `{w=N%, h=M}` — 宽度 + 最大高度（像素） - `{w=N%, h=M}` — 同时指定宽高（h 为像素时限制最大高度）
- 不写 → 默认 `w=80%`
- 两张图 `{w=N%}` 相加 ≤ 100% 时自动并排 - 两张图 `{w=N%}` 相加 ≤ 100% 时自动并排
### 2. `@import` — 导入数据文件 ### 2. `@import` — 导入数据文件
@ -68,20 +69,18 @@ chapters:
`using <script.py>` 加载项目根目录下的 Python 脚本，调用 `render(filepath)` → HTML。脚本不存在时降级为行号视图，不报错。 `using <script.py>` 加载项目根目录下的 Python 脚本，调用 `render(filepath)` → HTML。脚本不存在时降级为行号视图，不报错。
### 3. 代码块渲染 — ` ```lang ` ### 3. 代码块渲染
```markdown
```schemdraw ```schemdraw
import schemdraw import schemdraw
from schemdraw import elements as e from schemdraw import elements as e
with schemdraw.Drawing(show=False) as d: with schemdraw.Drawing(show=False) as d:
d += e.Resistor().right().label('R1') d += e.Resistor().right().label('R1')
``` ```
```
构建时在 markdown 之前执行：` ```lang ` 代码块 → `doc_builder/renderers/lang.py` → SVG/HTML。`mermaid` 等标签为 passthrough（浏览器渲染）。 构建时在 markdown 之前执行：代码块 → `doc_builder/renderers/<tag>.py` → SVG/HTML。`mermaid` 等标签为 passthrough（浏览器端渲染）。
### 4. 表格占位符 ### 4. 占位符
表格中 `—` 表示待补充数据。 表格中 `—` 表示待补充数据。
@ -91,10 +90,10 @@ with schemdraw.Drawing(show=False) as d:
章节 .md 文件 章节 .md 文件
│ │
├─→ @import 处理器（替换为渲染 HTML） ├─→ @import 处理器（替换为渲染 HTML）
├─→ 代码块渲染器（```schemdraw → SVG） ├─→ 代码块渲染器（```lang → 渲染输出）
└─→ Python-Markdown（→ HTML） └─→ Python-Markdown（→ HTML）
│ │
├─→ 图片尺寸扩展（{s=N%} / {w=N%}） ├─→ 图片尺寸扩展（{w=N%} / {h=N%}）
└─→ codehilite（代码高亮） └─→ codehilite（代码高亮）
│ │
▼ ▼