连接Read the Docs和GitHub Actions

我喜欢使用Read the Docs来构建（和版本控制！）我的文档，但我也喜欢使用Jupyter笔记本来编写教程。不幸的是，尽管笔记本可以在Read the Docs上执行，但它们运行起来可能需要很长时间，或者需要特殊的Docker环境来执行，这超出了平台的支持范围。在这种情况下，我需要将执行后的笔记本（通常是大型图像）检入我的git仓库，这会导致大量冗余。此外，执行后的笔记本往往会与代码的开发不同步。不再是这样了！

这个库通过在GitHub Actions上执行代码，上传构建工件（在本例中，执行后的Jupter笔记本），然后（只有在那时！）触发一个可以下载执行后的笔记本的Read the Docs构建来避免这些问题。

设置此工作流程仍需要一些工作，但这个库有三个部分使它变得更容易

1. 一个GitHub动作，可以用来触发Read the Docs上当前分支的构建。
2. 一个Sphinx扩展，它与GitHub API接口，以下载为目标的提交哈希产生的工件。
3. 一些文档，展示如何设置所有这些！

用法

以下详细介绍了使用此工作流程设置项目的步骤。但您也可以在此存储库中看到一个功能齐全的示例。文档源在 docs 目录中，而 .github/workflows 目录中包含一个工作流程，用于使用此包构建文档。渲染的页面可在 rtds-action.readthedocs.io 上找到。

1. 设置 Read the Docs

1. 首先，您需要像平常一样导入您的项目。如果您已经完成了，请不要担心：这也可以用于现有的 Read the Docs 项目。
2. 接下来，转到 Read the Docs 上您的项目管理员页面，点击 集成（URL 可能类似于 https://readthedocs.org/dashboard/YOUR_PROJECT_NAME/integrations/）。
3. 点击 添加集成 并选择 通用 API 入站 webhook。
4. 请注意此页面上的 webhook URL 和 token 以备后用。

您还应该在 GitHub 上编辑您的 webhook 设置，通过访问 https://github.com/USERNAME/REPONAME/settings/hooks 并点击 Read the Docs webhook 旁边的“编辑”。在该页面上，您应该取消选中 推送 选项。

2. 设置 GitHub Actions 工作流程

在此示例中，我们假设我们已将教程编写为 Jupyter 笔记本，并使用 Jupytext（因为您可能应该这样做！）保存为 Python 脚本，位于名为 docs/tutorials 的目录中。

首先，您需要将上面记录的 Read the Docs webhook URL 和 token 作为您的 GitHub 项目的“秘密”添加，通过访问 URL https://github.com/USERNAME/REPONAME/settings/secrets。我将它们分别命名为 RTDS_WEBHOOK_URL（包括 https！）和 RTDS_WEBHOOK_TOKEN。

对于此用例，我们可以创建工作流程 .github/workflows/docs.yml 如下所示

name: Docs
on: [push, release]

jobs:
  notebooks:
    name: "Build the notebooks for the docs"
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Set up Python
        uses: actions/setup-python@v2
        with:
          python-version: 3.8

      - name: Install dependencies
        run: |
          python -m pip install -U pip
          python -m pip install -r .github/workflows/requirements.txt

      - name: Execute the notebooks
        run: |
          jupytext --to ipynb --execute docs/tutorials/*.py

      - uses: actions/upload-artifact@v2
        with:
          name: notebooks-for-${{ github.sha }}
          path: docs/tutorials

      - name: Trigger RTDs build
        uses: dfm/rtds-action@v1
        with:
          webhook_url: ${{ secrets.RTDS_WEBHOOK_URL }}
          webhook_token: ${{ secrets.RTDS_WEBHOOK_TOKEN }}
          commit_ref: ${{ github.ref }}

在这里，我们还假设我们在 .github/workflows/requirements.txt 中添加了执行笔记本所需的依赖项的 pip 要求文件。请注意，在 upload-artifact 步骤中，我们给出了依赖于当前提交哈希的工件。这是至关重要的！我们还需要注意 notebooks-for- 前缀，因为我们稍后会使用它。

在此强调，此工作流程中唯一的“特殊”步骤是最后两个。您可以在之前的步骤中执行任何您想要生成工件的操作（例如，您可以使用 conda 而不是 pip），因为此工作流程对您如何到达那里并不挑剔！

3. 设置 Sphinx

最后，您可以编辑您的 Sphinx 文档的 conf.py 以添加对获取您的操作产生的工件的支持。以下是一个最小示例

import os

extensions = [... "rtds_action"]

# The name of your GitHub repository
rtds_action_github_repo = "USERNAME/REPONAME"

# The path where the artifact should be extracted
# Note: this is relative to the conf.py file!
rtds_action_path = "tutorials"

# The "prefix" used in the `upload-artifact` step of the action
rtds_action_artifact_prefix = "notebooks-for-"

# A GitHub personal access token is required, more info below
rtds_action_github_token = os.environ["GITHUB_TOKEN"]

# Whether or not to raise an error on Read the Docs if the
# artifact containing the notebooks can't be downloaded (optional)
rtds_action_error_if_missing = False

其中我们添加了自定义扩展并设置了所需的配置参数。

您需要向 Read the Docs 提供一个 GitHub 个人访问令牌（如果您的存储库是公开的，则只需要 public_repo 范围）。您可以通过访问 您的 GitHub 设置页面 生成新的令牌。然后，将其保存为环境变量（在本例中称为 GITHUB_TOKEN）在 Read the Docs 上。

开发

目前只是做个备注：如果您编辑 src/js/index.js，您必须运行 npm run package 以生成编译后的操作源。