场景
在更新一个开源库的时候,常常会增删改旧接口,这样的变动可能很频繁、细微,如果每次因此手动修改文档无疑是很繁琐的任务。因此亟需一条能自动解决以上问题的流水线。只要我发布了新版本,就会自动更新接口文档。
涉及技术
- 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 分区就能自动更新啦。