常见问题¶

Q1: 构建失败，提示找不到模块¶

A: 确保在构建前安装了所有依赖：

uv pip install .

Q2: API 文档没有生成¶

A: 检查以下几点：

确保没有使用 --no-api-doc 或 -A 参数
确保项目有可导入的 Python 模块
检查 CODE_ROOT 环境变量是否正确设置

Q3: 外链不显示¶

A:

检查 external_links.yaml 配置是否正确
确认 PROJECT 环境变量设置正确
查看浏览器控制台是否有 JavaScript 错误

Q4: 中文文档链接不存在¶

A: 确保：

中文文档以 _ZH.md 或 _ZH.rst 结尾
index_ZH.rst 存在并正确配置

Q5: 版本切换后页面不存在¶

A: 不同版本的文档结构可能不同：

旧版本可能没有某些新页面
切换版本会尝试访问相同路径，不存在时会跳回首页

Q6: 站点上残留孤儿页面，或旧 tag 仍是过时的主题外观¶

A: 增量部署不会删除文件，且 tag 页面保留其发布时的主题。两个问题都可以通过一次手动全量重建解决：触发 workflow_dispatch 并勾选 full: true（见使用 GitHub Actions 部署）。它会重建所有版本并整站替换，既清理孤儿文件，也统一刷新主题。