本文共 2698 字,大约阅读时间需要 8 分钟。
docfx 是微软出品一个 .NET API 文档框架,有一个理念是代码即文档,会根据项目代码自动生成 API 文档,即使没有写任何注释也会生成 API 文档,也有一些默认的主题可以配置,也可以自定义主题配置,详细介绍可以参考官方介绍
目前也有很多项目在使用 docfx 来生成文档,比如前段时间介绍过的 Reserver-Proxy
项目,也是看到了 reservse-proxy 项目配置了一个 Github Actions 来自动更新文档所以在我自己的项目里也增加了类似的配置,除了微软的项目还有很多社区开源项目在用,如果你也在做一些 .NET 类库类的开源项目,可以尝试一下
docfx 怎么使用可以参考官方文档,本文主要介绍如何使用 Github Actions 实现自动更新文档
更多可以参考:
自动更新文档 commit 示例
.git
目录包含git信息,不能删除)Actions 示例,源链接:
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" # 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 分支更新时再更新,修改分支名称即可
现在用的还是 2.x 版本,3.x 版本还没发布,3.x版本发布之后可以直接通过 dotnet tool
来安装更加方便和可扩展,目前 2.x 使用 choco
来安装命令行工具,需要依赖 Chocolatey,如果是 dotnet tool
有 dotnet 环境就可以了,就可以方便很多了
不仅仅是 docfx 生成文档,你也可以扩展其他类似的需求,使用 Github Actions 实现自动同步,更新
转载地址:http://jduki.baihongyu.com/