场景
在更新一个开源库的时候，常常会增删改旧接口，这样的变动可能很频繁、细微，如果每次因此手动修改文档无疑是很繁琐的任务。因此亟需一条能自动解决以上问题的流水线。只要我发布了新版本，就会自动更新接口文档。
涉及技术
- api-extractor，用于提取接口信息
- api-documenter，将提取到的信息处理为 markdown 文件
- docusaurus，老牌文档框架
- GitHub Action，运行流水线自动提交文档文件
在这个情况下，我不希望 docusaurus 与我本来的代码库混到一块，所以分开两个项目管理。这就涉及到将内容一个提交到第三方仓库的能力了，本文以 mind-elixir-core 和 mind-elixir/docs 为例。
配置文件
name: Node.js Package
on:
release:
types: [created]
workflow_dispatch:
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: pnpm/action-setup@v2
with:
version: 8
- uses: actions/setup-node@v3
with:
node-version: 18
registry-url: "https://registry.npmjs.org"
cache: "pnpm"
- run: pnpm i
- run: npm run build
- run: npm publish
env:
NODE_AUTH_TOKEN: ${{secrets.npm_token}}
- name: Checkout docs repository
uses: actions/checkout@v3
with:
repository: mind-elixir/docs
token: ${{ secrets.PAT }}
path: me-docs
- name: Generate API documentation
run: |
npm run doc
npm run doc:md
- name: Copy build results to docs repository
run: |
cp -r ./md/* ./me-docs/docs/api
cp -r ./md/* ./me-docs/i18n/ja/docusaurus-plugin-content-docs/current
cp -r ./md/* ./me-docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current
- name: Push changes to docs repository
run: |
cd me-docs
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
git add .
if git diff-index --quiet HEAD; then
echo "No changes to commit"
else
git commit -m "Update API documentation"
git push
fi
配置分析
push 操作的重点是在项目中配置 secrets.PAT。GitHub Action 运行的当前项目似乎是不需要 PAT 的，但如果推送到其他项目，PAT 就是必须的。
所谓的 PAT 其实就是 personal access token，带着它代表你有推送目标 GitHub 仓库的权限。
PAT 获取路径：
- 验证邮箱
- 点击 GitHub 右上角头像，选择 Settings
- 左侧栏选择 Developer settings
- 左侧栏选择 Personal access tokens
现时有两种 Token 可以选择，不过在 GitHub 内部使用 GitHub 的 Token，直接权限拉满大概也没什么问题。
拿到 PAT 之后在需要运行 Action 的仓库配置 secret，Action 在运行的时候就会自动取到。除此之外的内容就是一些显而易见的自动化脚本，不多加赘述，整体流程请看总结 ↓
总结
整个 GitHub Action 的基本流程就是：
- 拉取项目
- 构建项目
- 发布到 npm（需要 npm Token）
- 使用 api-extractor 提取接口信息，使用 api-documenter 生成 markdown 文件
- 拉取文档项目
- 把上面生成的 markdown 文档文件复制到文档项目（因为做了 i18n 所以复制了三遍）
- 然后提交文档仓库更新就好了
- 文档仓库更新后也会自动触发自己的 webhook 自动构建文档站
这么一套下来，mind-elixir-core 版本发布后，文档网站的 API 分区就能自动更新啦。
