利用 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 实现自动更新文档
文档示例
更多可以参考: https://weihanli.github.io/WeihanLi.Npoi/index.html
自动更新文档 commit 示例
自动更新文档流程
- 检出要使用的用于生成文档的分支代码
- 安装 docfx 命令行工具，推荐使用 choco 安装，因为执行 build 的 agent 上已经安装了 Chocolatey
- 使用 docfx 生成文档
- 检出 gh-pages 分支，用于托管文档的分支
- 删除 gh-pages 之前的文件（
.git目录包含git信息，不能删除） - 把第三步操作生成的文档复制到 gh-pages 分支下
- commit && push，提交代码并推送更新在线文档
Github Actions 示例配置
Actions 示例，源链接: https://github.com/WeihanLi/WeihanLi.Npoi/blob/dev/.github/workflows/docfx.yml
name: docfx build
on:
push:
branches:
- dev
jobs:
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"
# Run a build
- name: Build docs
run: "& docfx ./docfx.json"
working-directory: ./source
# Check out gh-pages branch to the 'docs' subdirectory
- name: Checkout docs
uses: actions/checkout@v2
with:
ref: gh-pages
path: docs
# Sync the site
- name: Clear docs repo
run: Get-ChildItem -Force -Exclude .git | ForEach-Object { Remove-Item -Recurse -Verbose -Force $_ }
working-directory: ./docs
- name: Sync new content
run: Copy-Item -Recurse -Verbose -Force "$env:GITHUB_WORKSPACE/source/_site/*" "$env:GITHUB_WORKSPACE/docs"
working-directory: ./docs
# update docs
- name: Commit to gh-pages and push
run: |
$ErrorActionPreference = "Continue"
git add -A
git diff HEAD --exit-code
if ($LASTEXITCODE -eq 0) {
Write-Host "No changes to commit!"
} else {
git config --global user.name "github-actions-docfx[bot]"
git config --global user.email "weihanli@outlook.com"
git commit -m "Updated docs from commit $env:GITHUB_SHA on $env:GITHUB_REF"
git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}
git push origin gh-pages
}
working-directory: ./docs
我这里是只要 dev 分支更新了就更新，你也可以根据需要当 master 分支更新时再更新，修改分支名称即可
More
现在用的还是 2.x 版本，3.x 版本还没发布，3.x版本发布之后可以直接通过 dotnet tool 来安装更加方便和可扩展，目前 2.x 使用 choco来安装命令行工具，需要依赖 Chocolatey，如果是 dotnet tool 有 dotnet 环境就可以了，就可以方便很多了
不仅仅是 docfx 生成文档，你也可以扩展其他类似的需求，使用 Github Actions 实现自动同步，更新
