部署 Sphinx 文档到 GitHub Pages 详细指南

部署 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 目录下执行cdpython/docsmakehtml

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

2. 手动部署到 GitHub Pages

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

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

构建文档：在项目根目录下，执行 Sphinx 构建命令，生成 HTML 文件，文件在build/html/目录下
```
makehtml# 或者直接使用 sphinx-build# sphinx-build -b html docs/source docs/build/html
```
准备部署目录：进入构建输出目录（如docs/_build/html或build/html），初始化一个 Git 仓库并设置远程地址
```
cd docs/build/html git init git remote add origin https://github.com/<你的用户名>/<你的仓库名>.git
```

创建并推送至 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：

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

3. 自动部署（GitHub Actions）

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

3.1 创建 GitHub Actions 工作流

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

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

3.2 编写工作流配置

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

name:Deploy Sphinx Documentationon:# 当主分支或开发分支有推送时触发push:branches:[main,master,develop]# 允许手动触发workflow_dispatch:jobs:build-and-deploy:runs-on:ubuntu-latestpermissions:contents:write# 需要写入内容权限pages:write# 需要操作 Pages 权限id-token:write# 需要生成 ID Tokensteps:# 步骤 1: 检出代码-name:Checkout repositoryuses:actions/checkout@v4with:fetch-depth:0# 确保获取完整的提交历史# 步骤 2: 设置 Python 环境-name:Set up Pythonuses:actions/setup-python@v4with:python-version:'3.10'cache:'pip'# 步骤 3: 安装依赖-name:Install dependenciesrun:|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 documentationrun:|cd python/docs make html# 步骤 5: 部署到 GitHub Pages-name:Deploy to GitHub Pagesuses:peaceiris/actions-gh-pages@v4with:# 文档源目录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 有足够的权限：

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

3.4 测试自动部署

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

gitadd.github/workflows/deploy-docs.ymlgitcommit -m"Add GitHub Actions workflow for docs deployment"gitpush 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扩展：

pipinstallsphinx-multiversion

在conf.py中添加：

extensions=[# 其他扩展...'sphinx_multiversion',]# 配置 sphinx-multiversionsmv_tag_whitelist=r'^v\d+\.\d+\.\d+$'# 只包含版本标签smv_branch_whitelist=r'^main$|^master$'# 只包含主分支smv_remote_whitelist=r'^origin$'# 只包含 origin 远程仓库smv_outputdir_format='{ref.name}'# 输出目录格式