一些自动化集成的经验

自动使用 pdoc 生成 API 文档，并发布到 vercel。

由于 vercel 的运行环境不支持 Python 3，所以需要把 pdoc 生成工作放到 Github Action 上。

编写 Github Action 的配置：

# deploy on vercel
name: pdoc

on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]
  workflow_dispatch:

jobs:
  deploy:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    steps:
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - uses: actions/checkout@v2

      - uses: actions/setup-python@v2
        with:
          python-version: '3.7.10'

      - name: poetry install
        run: |
          pip install poetry
          export POETRY_VIRTUALENVS_CREATE=false
          poetry install -n

      - name: run pdoc
        run: |
          pdoc --version
          pdoc --html -o ./docs mirai

      - name: prepare vercel project
        run: |
          mv ./docs/mirai ./docs/yiri-mirai-api

      - uses: actions/setup-node@v1
        with:
         node-version: '14.x'

      - name: install vercel cli
        run: npm i vercel

      - name: deploy
        run: |
          vercel link "$PWD/docs/yiri-mirai-api" --confirm --token=${{ secrets.VERCEL_TOKEN }}
          vercel deploy "$PWD/docs/yiri-mirai-api" --prod --token=${{ secrets.VERCEL_TOKEN }}

简单解析一下这个配置：

第一步，安装 poetry，通过 poetry 安装依赖。pdoc 在项目的 dev-dependencies 中，也会被自动安装。

- name: poetry install
  run: |
    pip install poetry
    export POETRY_VIRTUALENVS_CREATE=false
    poetry install -n

通过设置环境变量 POETRY_VIRTUALENVS_CREATE=false，可以让 poetry 把包安装到全局 Python 环境中，否则会出现找不到 pdoc 的问题。

第二步，运行 pdoc，生成 API 文档。

- name: run pdoc
  run: |
    pdoc --version
    pdoc --html -o ./docs mirai

mirai 是项目的名称。这里使用了 --html，生成网页格式，可以直接部署到 vercel。

第三步，重命名生成的文档的文件夹。因为 vercel link 会根据文档的文件夹名称来创建项目，所以这里需要把文档的文件夹名称改为 yiri-mirai-api，和最终需要的名称一致。

- name: prepare vercel project
  run: |
    mv ./docs/mirai ./docs/yiri-mirai-api

第四步，安装 vercel cli。

- name: install vercel cli
  run: npm i vercel

第五步，运行 vercel cli，把文档部署到 vercel。

- name: deploy
  run: |
    vercel link "$PWD/docs/yiri-mirai-api" --confirm --token=${{ secrets.VERCEL_TOKEN }}
    vercel deploy "$PWD/docs/yiri-mirai-api" --prod --token=${{ secrets.VERCEL_TOKEN }}

这里使用了 secrets.VERCEL_TOKEN，这个是在 Vercel 的管理员页面获取的。

因为 token 拥有 vercel 账户的全部权限，不能公开，所以使用了 Github 的加密机制。将 token 保存到项目机密中，在此处以变量的方式引用。参见 Github 加密机密。

BTW，vercel cli 一点都不像个 cli，各种需要二次输入的东西，完全不适合自动化……

以上。