在发布新的Python软件包时，我想发布从源代码构建的文档到GitHub Pages。与我上次设置工作流程的最后一次（那是构建OpenAPI文档）相比，这个过程变得更简单，更简化。

免责声明：截至本文时，我使用的方法仍然标记为 beta ，所以ymmv）。

这是一个Python项目，我正在使用Sphinx作为文档。以下是构建和发布项目文档的完整github操作YAML文件。我将分解每个部分并描述整个工作流程。

name: Publish Documentation

on:
  push:
    branches:
      - 'main'
    paths:
      - 'docs/**'
      - 'src/**'

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:

  build:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'

      - name: Install Dependencies
        run: python3 -m pip install --editable '.[dev]'

      - name: Build Sphinx Docs
        run: sphinx-build -b html docs/ build/docs/

      - name: Upload Artifact
        uses: actions/upload-pages-artifact@v2
        with:
          path: 'build/docs/'

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

存储库设置

首先，需要为存储库设置github页面。这是在设置 - > 页面（在侧边栏中） - > 构建和部署。我正在使用 github动作（beta），而不是从分支部署 - 旧方法。

还需要专门针对github页面构建环境。默认情况下，这是我在新仓库中创建的。环境让您定义围绕相关构建的其他规则和秘密。这里的关键是，只有main分支用于部署文档。

检查设置 - > 环境（在侧边栏中）查看您是否有github-pages环境。如果不是，请创建一个并添加main分支作为唯一的部署分支。对于我在这里描述的工作流程，不需要其他环境设置。

Trigger (On)

on:
  push:
    branches:
      - 'main'
    paths:
      - 'docs/**'
      - 'src/**'

在这个项目中，我决定始终建立在任何推向main的推动下，在这些推动下，将变更已变化为docs/和src/目录。不会影响文档的任何其他更改（喜欢测试，读书我的读书我）。

branches和paths的过滤选项是防止工作流程运行的强大工具。

Permissions

permissions:
  contents: read
  pages: write
  id-token: write

对于某些动作，需要授予工作流程执行这些权限。可能的权限记录在here。我授予此工作流的三个权限：

• 内容 - 授予阅读对存储库内容的访问。仅当存储库设置为私有时，这才需要。一旦切换到 public 不再需要此权限。
• 页面 - 这允许工作流程请求github页面构建。
• id -token - 工作流将获取OIDC令牌。此许可用于许多其他GitHub动作工作流程（例如PYPI Publishing或AWS IAM角色假设）。在这里，它用于验证部署起源于适当的来源。

我已经在全球级别的工作流程中定义了权限，但是您还可以在工作级别定义权限以进行更细粒度的访问控制。

Concurrency

concurrency:
  group: "pages"
  cancel-in-progress: false

这是一个非常方便的控制，要记住任何工作流程，您要确保在任何给定时刻都发生一个实例。我不希望多次提交main来触发多个并行文档构建。通过为工作流和cancel-in-progress设置一个组标签，我现在有一个队列，每个提交都将在其中构建和发布。

另外，如果我将cancel-in-progress设置为true 10

The Job

工作流的工作由许多步骤组成。该作业本身具有两个用于配置的键。

jobs:

  build:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest

• environment - 这定义了用于工作的环境。
• 名称 - 环境的名称。我将github-pages设置为使用以前的设置中的环境。
• url - 这是工作输出的URL。由于这是发布到github页面的，因此URL将是指向最终文档的链接（static github.io url）。该语法是从ID deployment的步骤中引用值。
• runs-on - 工作将执行的主机类型。在大多数示例中，这通常是ubuntu-latest，除非您有特定的构建需求，否则您应该将其保留。

工作设置

    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'

前两个步骤是设置作业的环境。 checkout action将在触发参考文献中查看存储库。 setup-python action将设置所需的Python运行时间。我的软件包支持Python 3.9+，因此我针对的是我的构建环境的最小版本。

文档构建

      - name: Install Dependencies
        run: python3 -m pip install --editable '.[dev]'

      - name: Build Sphinx Docs
        run: sphinx-build -b html docs/ build/docs/

接下来的两个步骤没有关联的操作。他们只运行两个命令：包含包装的所有开发要求的pip install，而sphinx-build生成了HTML文档。

将某些命令分为自己的步骤可以有助于解决故障排除。如果此工作流失败，我会知道它在依赖性安装过程中是否失败或在构建过程中是否失败。

出版

      - name: Upload Artifact
        uses: actions/upload-pages-artifact@v2
        with:
          path: 'build/docs/'

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

最后两个步骤完成了uploading the artifact的过程（build/docs/ sphinx-build输出到输出的build/docs/目录），然后使用deploy-pages action。

id字段具有deployment的值，该值在environment部分中使用：

url: ${{ steps.deployment.outputs.page_url }}

上载工件的动作并不能做得太多，但是它专门解决了github页面周围的所有细微差别。您可以查看动作的源here。它将tar路径（由with选项提供），然后致电upload artifact action。文物的名字是github-pages，有1天的到期。该工件具有部署操作所需的名称和格式。一切都起作用（到目前为止）。

成功

结果是在项目的github页面URL上可用的每项可用的main订单上的文档的新构建。

我的工作流程用于Python软件包的文档，但只有两个部分特定于此：运行时设置，以及安装依赖关系并构建文档的步骤。您可以将其交换为其他任何运行时和/或文档框架，其余的应该几乎相同。