leetcuda-tex-to-readthedocs
LeetCUDA 书稿 LaTeX 到 Read the Docs 站点的转换管线维护 skill(站点目录 LeetCUDA/docs/readthedocs/)。当任务涉及:改完书稿后让站点同步、改转换器 convert/、本地构建与预览 build.sh、内容核对 convert.verify、浏览器验收 tools.visual_check、版式与模板(_templates、_static
SKILL.mddocs/readthedocs/skills/leetcuda-tex-to-readthedocs/SKILL.md
GitHubLeetCUDA 书稿 → Read the Docs 站点
把 kernels/interview/book/ 下的书稿 tex 逐章转换成网页:公式走 MathJax 实时渲染,TikZ 图编译成 SVG,代码清单按 linerange 从冻结源码抽出来贴进页面。站点 https://leetcuda.readthedocs.io。
原书 tex、源码、图片一律不改:转换只读原文件,产物只写进 docs/readthedocs/build/(已 gitignore)。
开始前
conda activate cdit—— 站点构建统一用这个环境(Sphinx 7.4.7 + myst-parser 4.0.0 + sphinx-rtd-theme 3.0.2,版本见requirements.txt)。- 站点根 =
/workspace/dev/vipshop/LeetCUDA/docs/readthedocs/,下文命令都在该目录下执行。 - 先按「改动落点表」定位落点,再按需查
references/;不要凭直觉改转换器。
改动落点表
| 改了什么 | 要做的事 | 细节 |
|---|---|---|
| 中文正文 / 公式 / 表格 / 数学宏 | push 即可:构建期从 tex 现转,中英文自动同步 | — |
| TikZ 图内中文文字、新增含中文的图 | 先补词典再 push,否则 RTD 的 post_build「英文图集完整」必红 |
references/english.md |
| 封面文案 | 重编译入库的 figures/misc/cover.pdf 并 commit;英文封面另跑 tools.build_cover_en 并 commit 产物 |
references/english.md |
转换器 convert/*.py |
改完必须跑全量 ./build.sh(含 28 项核对)+ 浏览器验收 |
references/pipeline.md、references/acceptance.md |
| 版式 / 模板 / CSS / JS | 先 touch build/src/index.md 再 ./build.sh,否则静态文件不重拷、预览还是旧样式 |
references/layout-frontend.md |
| 「下载 PDF」按钮(落位/样式)或其链接 | 按钮默认在「下一页」右边(顶部 + 页脚两行);链接只改仓库根 README.md 的 [leetcuda-pdf] 一行,站点与核对都跟着变 |
references/layout-frontend.md |
| 首页标题右侧的 Trendshift 徽章 | 片段在 convert/__main__.py 的 BOOK_BADGE(照抄仓库根 README.md),落位与宽度在 custom.css 的 .rtd-trendshift |
references/layout-frontend.md |
右上角仓库按钮(显示 xlite-dev/LeetCUDA,落位/链接/样式) |
模板在 _templates/breadcrumbs.html 的 breadcrumbs_aside,链接取 convert/readme.py 的 REPO_URL,样式在 custom.css 的 .rtd-repo-link;convert/verify.py 逐页核对 |
references/layout-frontend.md |
| RTD 构建失败 | 先看 pre_build(apt 包 / pandoc 版本),再看 post_build 打印的核对项 |
references/sync-and-deploy.md |
| 核对项本身 | 新增/调整 convert/verify.py 的 check_*,接入 verify() 与 main() |
references/acceptance.md |
本地构建与预览
conda activate cdit
cd /workspace/dev/vipshop/LeetCUDA/docs/readthedocs
pip install -r requirements.txt # 首次或依赖变更后
./build.sh # 转换 → sphinx-build → 内容核对
python -m http.server -d build/html 8000 # 本机浏览器看 build/html/index.html
TikZ 全量编译约 3–5 分钟,调试时务必缩短:
./build.sh --skip-tikz # 复用已有 SVG,只重跑文本转换 + 构建 + 核对
python -m convert --only ch00-profiling,ch16-fa2-splitq-mma # 只转几章
python -m convert --jobs 8 # TikZ 并行度
python -m convert --force-tikz # 忽略缓存重编全部 TikZ
python -m convert --skip-tikz --no-assemble # 只跑 tex→md
远程 SSH 开发要在 VS Code 里看效果,必须做端口转发(内置浏览器在你本机渲染),见 references/acceptance.md。
验收:三层,缺一层就会漏
- 文件级:
python -m convert.verify --src build/src --html build/html(28 项,build.sh已含)。 - 浏览器级:
python -m tools.visual_check --html build/html --out build/shots/chapters—— MathJax 报错、可见字面残迹、控制台报错、404 资源、整页截图。 - 版式几何(已并进 visual_check):图片/表格是否居中、有没有元素(过宽公式、宽表)撑出正文栏。
两条铁律:任一项不过就修 tex/转换器,不许绕过核对;0 警告 ≠ 页面正确,总数阈值会掩盖单点丢失(表格 126→125 时「≥90%」照样通过,改成逐章比对立刻暴露)。
参考文件
references/pipeline.md— 转换管线全貌(编排、章号/表格、TikZ→SVG、数学宏)、命令速查、目录结构、增量构建与 gitignore 陷阱。references/layout-frontend.md— 三栏版式与居中、模板覆盖规则(page.html / layout.html / 两个整文件副本各管什么)、图片/表格/过宽公式、「下载 PDF」按钮的落位与兜底、中英切换按钮的落位。references/english.md— Google 翻译切换机制与判定阈值、英文图集(词典/掩码/校验/换图)、英文封面离线生成。references/acceptance.md— 三层验收细节、28 项核对清单、visual_check 参数、本地与远程(VS Code 端口转发)预览。references/pitfalls.md— 已证伪路线与踩坑(TikZ、公式、正文结构),附页面上可见的症状。references/sync-and-deploy.md— 内容更新与自动同步对照表、改稿检查清单、RTD 建站步骤、已知边界。