如何配置GitHub Pages每次推送时自动构建Sphinx+Doxygen文档

1. 前置准备 #

在仓库docs目录下新建requirements.txt，写入你的Sphinx构建依赖，示例内容：

sphinx==7.2.6
sphinx-rtd-theme==2.0.0
# 其他你用到的Sphinx扩展

2. 配置自动构建工作流 #

在仓库根目录创建.github/workflows/sphinx-deploy.yml文件，内容如下：

name: 自动构建部署Sphinx文档
on:
  push:
    branches: ["master"]
    # 仅当docs目录下内容变更时触发构建，不需要可以删掉这行
    paths: ["docs/**"]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: 拉取仓库代码
        uses: actions/checkout@v4

      - name: 配置Python环境
        uses: actions/setup-python@v5
        with:
          python-version: "3.10"

      - name: 安装构建依赖
        run: |
          python -m pip install --upgrade pip
          pip install -r docs/requirements.txt

      - name: 构建Sphinx文档
        run: sphinx-build -b html docs/source docs/build

      - name: 部署文档到gh-pages分支
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/build
          # 如果你要部署到master分支的/docs/build路径，去掉上面的配置，改用下面的提交命令，*不推荐该方案*
          # run: |
          #   git config --global user.name "github-actions[bot]"
          #   git config --global user.email "github-actions[bot]@users.noreply.github.com"
          #   git add docs/build
          #   git commit -m "docs: 自动更新构建产物"
          #   git push

3. 配置GitHub Pages源 #

• 进入仓库的Settings页面，找到左侧菜单栏的Pages选项
• 在Build and deployment区域的Source下拉框选择Deploy from a branch
• Branch下拉框选择gh-pages，路径选根目录/，保存即可

注意事项 #

• 第一次推送工作流文件后，会自动触发一次构建，构建完成后gh-pages分支会自动创建
• 提前在仓库Settings -> Actions -> General -> Workflow permissions中勾选Read and write permissions，给工作流推送分支的权限

内容的提问来源于stack exchange，提问作者gavrilikhin.d