常见问题¶
构建与预览¶
为什么 notebook 构建时不执行？¶
构建文档应保持快速、稳定、可重复。当前配置只渲染 notebook 中已保存的输出，
不在 mkdocs build 时重新运行代码。这样每次构建秒级完成，不受仿真代码耗时影响。
需要更新输出时：在本地启动 Jupyter（uv run jupyter notebook），
手动执行目标 notebook，保存后提交。
如何添加新 FAQ？¶
在 docs/faq/ 目录下补充内容，问题用三级标题（###），
回答直接写在标题下方。如需在导航中单独列出某个 FAQ 条目，
在 mkdocs.yml 的 nav 段中注册。
数据管理¶
大型仿真结果应该放在哪里？¶
不要直接提交到文档仓库。可以这样处理：
- 小型数据（几个 MB 以内）：作为 notebook 输出直接保存。
- 中型数据：上传到发布附件、Zenodo 或课题组文件服务器，在文档中记录链接。
- 大型数据：使用 DVC 等数据版本管理工具，数据与文档代码分离。
环境问题¶
uv sync 失败？¶
确认 Python 版本 ≥ 3.11，uv 已安装（uv --version）。如使用系统 Python 有冲突，
可以先用 uv python install 3.11 安装独立 Python 再同步。