利用 Github Actions 自动更新 docfx 文档

利用 Github Actions 自动更新 docfx 文档

Intro

docfx 是微软出品一个 .NET API 文档框架，有一个理念是代码即文档，会根据项目代码自动生成 API 文档，即使没有写任何注释也会生成 API 文档，也有一些默认的主题可以配置，也可以自定义主题配置，详细介绍可以参考官方介绍 https://dotnet.github.io/docfx/

目前也有很多项目在使用 docfx 来生成文档，比如前段时间介绍过的 Reserver-Proxy 项目，也是看到了 reservse-proxy 项目配置了一个 Github Actions 来自动更新文档所以在我自己的项目里也增加了类似的配置，除了微软的项目还有很多社区开源项目在用，如果你也在做一些 .NET 类库类的开源项目，可以尝试一下

docfx 怎么使用可以参考官方文档，本文主要介绍如何使用 Github Actions 实现自动更新文档

文档示例

利用 Github Actions 自动更新 docfx 文档_Github Actions

利用 Github Actions 自动更新 docfx 文档_Github Actions_02

更多可以参考: https://weihanli.github.io/WeihanLi.Npoi/index.html

自动更新文档 commit 示例

利用 Github Actions 自动更新 docfx 文档_Github Actions_03

自动更新文档流程

  1. 检出要使用的用于生成文档的分支代码
  2. 安装 docfx 命令行工具，推荐使用 choco 安装，因为执行 build 的 agent 上已经安装了 Chocolatey
  3. 使用 docfx 生成文档
  4. 检出 gh-pages 分支，用于托管文档的分支
  5. 删除 gh-pages 之前的文件（.git目录包含git信息，不能删除）
  6. 把第三步操作生成的文档复制到 gh-pages 分支下
  7. commit && push，提交代码并推送更新在线文档

Github Actions 示例配置

Actions 示例，源链接:https://github.com/WeihanLi/WeihanLi.Npoi/blob/dev/.github/workflows/docfx.yml

name: docfx buildon: push: branches:  - devjobs: build: name: Build runs-on: windows-latest steps:  # Check out the branch that triggered this workflow to the 'source' subdirectory  - name: Checkout Code  uses: actions/checkout@v2  with:   ref: dev   path: source  - name: install DocFX  run: "& choco install docfx -y"  # R.........