UsubeniFantasy
·
使用 Github Action 自动更新开源项目 API 文档
内容提要
通过使用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分区自动更新。
延伸解读
自动化文档更新的必要性
在开源项目中，接口频繁变动使得手动更新文档变得繁琐且容易出错。通过自动化流程，开发者可以节省时间，确保文档与代码保持一致，提升项目的可维护性和用户体验。
个人访问令牌（PAT）的安全性
配置GitHub Action时，使用个人访问令牌（PAT）是确保推送权限的关键。获取和管理PAT时，开发者应注意其权限设置，避免不必要的安全风险，确保只授予必要的访问权限。
文档与代码分离的优势
将文档与代码库分开管理，可以使项目结构更加清晰，便于团队协作。这样做不仅可以独立更新文档，还能减少代码库的复杂性，提高开发效率。
延伸问答
如何使用 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）以确保能够推送到其他项目，并配置相关的自动化脚本。
