UsubeniFantasy
·
使用 Github Action 自动更新开源项目 API 文档
💡
原文中文，约2300字，阅读约需6分钟。
📝
内容提要
通过使用api-extractor提取接口信息，api-documenter生成markdown文档，并利用GitHub Action自动提交到文档仓库，实现文档的自动更新。配置个人访问令牌（PAT）以确保顺利推送到其他项目。
🎯
关键要点
- 在更新开源库时，频繁的接口变动需要自动更新文档。
- 使用api-extractor提取接口信息，api-documenter生成markdown文档。
- 使用docusaurus作为文档框架，GitHub Action实现文档自动提交。
- 将文档与代码库分开管理，使用第三方仓库。
- 配置GitHub Action时需要设置个人访问令牌（PAT）以推送到其他项目。
- PAT是个人访问令牌，代表推送目标GitHub仓库的权限。
- 获取PAT的步骤包括验证邮箱和在GitHub设置中生成Token。
- GitHub Action的基本流程包括拉取项目、构建、发布到npm、提取接口信息、生成文档、更新文档仓库。
- 文档仓库更新后会自动触发构建文档站，确保API分区自动更新。
❓
延伸问答
如何使用 GitHub Action 自动更新开源项目的文档？
通过使用 api-extractor 提取接口信息，api-documenter 生成 markdown 文档，并利用 GitHub Action 自动提交到文档仓库。
什么是个人访问令牌（PAT），它有什么作用？
个人访问令牌（PAT）是用于代表推送目标 GitHub 仓库权限的令牌，必须在推送到其他项目时配置。
如何获取 GitHub 的个人访问令牌（PAT）？
验证邮箱后，在 GitHub 设置中选择 Developer settings，然后选择 Personal access tokens 生成 Token。
使用 GitHub Action 更新文档的基本流程是什么？
基本流程包括拉取项目、构建、发布到 npm、提取接口信息、生成文档、更新文档仓库。
为什么要将文档与代码库分开管理？
将文档与代码库分开管理可以避免混淆，并允许使用第三方仓库进行文档管理。
在配置 GitHub Action 时需要注意哪些事项？
需要设置个人访问令牌（PAT）以确保能够推送到其他项目，并配置相关的自动化脚本。
➡️
