GitHub Actions 文档部署指南

GitHub Actions 文档部署指南#

本指南详细说明了如何使用 GitHub Actions 将 DP-EVA 的 Sphinx 文档自动构建并发布到 GitHub Pages。

1. 部署架构#

我们采用 GitHub Pages + GitHub Actions 的自动化部署方案。

  • 触发条件:

    • push 到 main 分支: 部署为 latest 版本。

    • push 到 v* 标签 (Tag): 部署为对应版本号 (如 v0.6.0)。

  • 构建环境: ubuntu-latest + python 3.x。

  • 发布目标: gh-pages 分支 (作为静态站点源)。

2. 前置配置 (Repository Settings)#

在 GitHub 仓库设置中，需完成以下配置：

  1. 进入 Settings > Pages。

  2. 在 Build and deployment 部分：

    • Source: 选择 Deploy from a branch。

    • Branch: 选择 gh-pages 分支，目录选择 / (root)。

  3. 确保 GITHUB_TOKEN 拥有写入权限 (Settings > Actions > General > Workflow permissions > Read and write permissions)。

3. 工作流文件详解 (.github/workflows/docs-deploy.yml)#

3.1 权限与前置门禁#

工作流默认权限是 contents: read。main push、v* tag 和手动触发都必须先通过 release-validation；该 prerequisite 只调用 gate manifest 的共享 release profile， 不复制其命令。只有声明 needs: release-validation 的 deploy job 获得 contents: write，因此未经检查的触发不会写入 Pages 分支。

3.2 关键步骤说明#

  1. Release Validation: 在只读权限下安装 release 所需依赖，并执行共享 release profile。

  2. Checkout: deploy job 使用 fetch-depth: 0 获取完整版本信息。

  3. Build: deploy job 通过 manifest 的 docs_build gate 生成静态文件。

  4. Deploy: 仅该依赖 job 使用 peaceiris/actions-gh-pages。

    • destination_dir: 动态设置为 latest (对应 main 分支) 或 vX.Y.Z (对应 Tag)。

    • keep_files: true: 增量发布，确保推送新版本时不会删除旧版本目录。

4. 多版本管理策略#

当前采用目录隔离策略：

  • 根目录 (/): 可放置一个重定向页 (index.html)，自动跳转到 /latest/。

  • /latest/: 始终对应 main 分支的最新构建。

  • /v0.6.0/, /v0.5.0/: 对应发布的 Tag 版本。

4.1 根目录重定向 (index.html)#

建议在 gh-pages 分支根目录手动或通过 Action 维护一个 index.html:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="refresh" content="0; url=latest/">
    <title>Redirecting...</title>
</head>
<body>
    <p>Redirecting to <a href="latest/">latest documentation</a>...</p>
</body>
</html>

5. 本地验证#

在提交 Action 前，建议在本地模拟构建：

# 1. 清理旧构建
cd docs && make clean

# 2. 修复链接
python scripts/fix_links.py

# 3. 构建
make html

# 4. 预览 (需 Python)
python -m http.server --directory build/html 8000
# 访问 http://localhost:8000

6. 故障排查#

  • 构建失败 (ImportError): 检查 pip install -e . 是否成功，确保 src 目录被正确加入 PYTHONPATH。

  • 样式丢失: 检查 _static 目录是否被正确上传，通常由 .nojekyll 文件缺失导致 (Sphinx 主题常包含下划线开头的目录，GitHub Pages 默认会忽略它们)。

    • 注: peaceiris/actions-gh-pages 会自动创建 .nojekyll。

7. 后续优化#

  • 集成 sphinx-multiversion 插件，在侧边栏自动生成版本切换下拉菜单。

  • 添加 PR 预览功能 (Deploy Preview)，利用 Netlify 或 GitHub Actions Artifacts。

目录