部署 Sphinx 文档到 GitHub Pages 指南

本文将详细介绍如何将 Sphinx 生成的文档部署到 GitHub Pages，包括手动部署和使用 GitHub Actions 的自动部署方案。我们将以 dlt645 项目的 Python 版本文档为例进行说明。

1. 准备工作

1.1 项目结构

在开始之前，让我们先了解一下典型的 Sphinx 文档项目结构（以 dlt645/python/docs 为例）：

docs/
├── source/
│   ├── conf.py          # Sphinx 配置文件
│   ├── index.rst        # 文档首页
│   ├── modules.rst      # 模块索引
│   └── ...              # 其他文档源文件
├── build/               # 构建输出目录
│   └── html/            # HTML 文档输出
├── Makefile             # 构建脚本
└── make.bat             # Windows 构建脚本

1.2 确保 Sphinx 配置正确

在 conf.py 中，确保以下配置项正确设置：

# conf.py

# 项目信息
project = 'dlt645'
copyright = '2026, 陈东宇'
author = '陈东宇'
release = 'v1.4.0'

# 确保 sphinx.ext.githubpages 扩展已启用
extensions = [
    # 其他扩展...
    'sphinx.ext.githubpages',
]

# HTML 主题配置
html_theme = 'sphinx_rtd_theme'
html_theme_options = {
    'collapse_navigation': False,
    'navigation_depth': -1,
}

1.3 生成 HTML 文档

首先，确保能够成功生成 HTML 文档：

# 在 docs 目录下执行
cd python/docs
make html

生成的 HTML 文档将位于 build/html/ 目录下。

2. 手动部署到 GitHub Pages

手动部署适合简单项目或初次部署测试。

2.1 推送 HTML 文件到 gh-pages 分支

1. 构建文档：在项目根目录下，执行 Sphinx 构建命令，生成 HTML 文件，文件在build/html/目录下

   make html
   # 或者直接使用 sphinx-build
   # sphinx-build -b html docs/source docs/build/html
   

   

2. 准备部署目录：进入构建输出目录（如 docs/_build/html或 build/html），初始化一个 Git 仓库并设置远程地址

   cd docs/build/html
   git init
   git remote add origin https://github.com/<你的用户名>/<你的仓库名>.git
   

   

3. 创建并推送至 gh-pages 分支：将生成的所有文件提交并强制推送到远程仓库的 gh-pages分支

   # 添加所有文件
   git add .
   
   # 提交
   git commit -m "Deploy Sphinx documentation to GitHub Pages"
   
   # 推送到远程仓库
   git push -f origin main:gh-pages
   

   

2.3 配置 GitHub Pages

部署完成后，需要在 GitHub 仓库中配置 Pages：

1. 登录 GitHub，进入项目仓库
2. 点击 Settings → Pages
3. 在 Source 部分，选择 gh-pages 分支和 /(root) 目录
4. 点击 Save

3. 自动部署（GitHub Actions）

使用 GitHub Actions 可以实现文档的自动构建和部署，当代码变更时自动更新文档。

3.1 创建 GitHub Actions 工作流

在项目根目录下创建 .github/workflows/ 目录，并添加部署工作流文件：

mkdir -p .github/workflows
touch .github/workflows/deploy-docs.yml

3.2 编写工作流配置

编辑 deploy-docs.yml 文件，添加以下内容：

name: Deploy Sphinx Documentation

on:
  # 当主分支或开发分支有推送时触发
  push:
    branches: [ main, master, develop ]
  # 允许手动触发
  workflow_dispatch:

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write  # 需要写入内容权限
      pages: write     # 需要操作 Pages 权限
      id-token: write  # 需要生成 ID Token
    steps:
      # 步骤 1: 检出代码
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 确保获取完整的提交历史

      # 步骤 2: 设置 Python 环境
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'
          cache: 'pip'

      # 步骤 3: 安装依赖
      - name: Install dependencies
        run: |
          pip install --upgrade pip
          pip install -r python/requirements.txt
          pip install sphinx sphinx-rtd-theme sphinx-autodoc-typehints sphinx-copybutton

      # 步骤 4: 生成 HTML 文档
      - name: Build HTML documentation
        run: |
          cd python/docs
          make html

      # 步骤 5: 部署到 GitHub Pages
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          # 文档源目录
          publish_dir: ./python/docs/build/html
          # 提交信息
          commit_message: "Deploy Sphinx docs for ${{ github.sha }}"
          # 个人访问令牌（如果需要）
          github_token: ${{ secrets.GITHUB_TOKEN }}
          # 推送的分支
          publish_branch: gh-pages

3.3 配置权限

确保 GitHub 仓库的 Actions 有足够的权限：

1. 进入仓库 Settings → Actions → General
2. 在 Workflow permissions 部分，选择 Read and write permissions
3. 勾选 Allow GitHub Actions to create and approve pull requests
4. 点击 Save

3.4 测试自动部署

提交工作流文件到主分支：

git add .github/workflows/deploy-docs.yml
git commit -m "Add GitHub Actions workflow for docs deployment"
git push origin main

然后在 GitHub 仓库的 Actions 标签页中查看部署进度。

可以看到我最新提交的一次action已经成功

4. 高级配置

4.1 自定义域名

如果需要使用自定义域名，可以在 gh-pages 分支根目录添加 CNAME 文件：

echo "docs.dlt645.example.com" > CNAME

然后在 DNS 服务商处添加 CNAME 记录，指向 username.github.io。

4.2 文档版本管理

对于多版本文档，可以使用 sphinx-multiversion 扩展：

pip install sphinx-multiversion

在 conf.py 中添加：

extensions = [
    # 其他扩展...
    'sphinx_multiversion',
]

# 配置 sphinx-multiversion
smv_tag_whitelist = r'^v\d+\.\d+\.\d+$'  # 只包含版本标签
smv_branch_whitelist = r'^main$|^master$'  # 只包含主分支
smv_remote_whitelist = r'^origin$'         # 只包含 origin 远程仓库
smv_outputdir_format = '{ref.name}'        # 输出目录格式

然后使用 sphinx-multiversion 命令生成多版本文档：

sphinx-multiversion source build/html

4.3 文档搜索优化

为了让 GitHub Pages 正确处理 Sphinx 的搜索功能，需要确保 .nojekyll 文件存在，以禁用 Jekyll 的处理。

5. 常见问题与解决方案

5.1 文档样式丢失

问题：部署后文档样式丢失，显示为原始 HTML。

解决方案：

• 确保添加了 .nojekyll 文件
• 检查 html_baseurl 配置是否正确
• 确保静态资源路径配置正确

5.2 部署权限错误

问题：GitHub Actions 部署时出现权限错误。

解决方案：

• 确保工作流文件中设置了正确的权限
• 检查仓库的 Actions 权限设置
• 如果使用个人访问令牌，确保令牌有足够的权限

5.3 自动部署不触发

问题：推送代码后自动部署不触发。

解决方案：

• 检查工作流文件中的 on 触发条件
• 确保推送的分支与配置的分支匹配
• 查看 Actions 日志了解具体原因

5.4 文档更新不及时

问题：部署后文档内容未更新。

解决方案：

• 确保构建命令正确生成了新文档
• 检查 GitHub Pages 的缓存设置
• 尝试强制刷新浏览器或使用无痕模式访问

6. 总结

本文介绍了两种将 Sphinx 文档部署到 GitHub Pages 的方法：

1. 手动部署：适合简单项目或初次测试，包括直接推送和使用 git worktree 两种方式。
2. 自动部署：使用 GitHub Actions 实现文档的自动构建和部署，提高开发效率。

通过正确配置和部署，可以确保 Sphinx 文档始终保持最新，并通过 GitHub Pages 方便地分享给用户。

参考链接

• Sphinx 官方文档
• GitHub Pages 官方文档
• GitHub Actions 官方文档
• peaceiris/actions-gh-pages