利用 Github Actions 自動更新 docfx 文檔

Intro

docfx 是微軟出品一個 .NET API 文檔框架，有一個理念是代碼即文檔，會根據(jù)項目代碼自動生成 API 文檔，即使沒有寫任何注釋也會生成 API 文檔，也有一些默認的主題可以配置，也可以自定義主題配置，詳細介紹可以參考官方介紹 https://dotnet.github.io/docfx/

目前也有很多項目在使用 docfx 來生成文檔，比如前段時間介紹過的 Reserver-Proxy 項目，也是看到了 reservse-proxy 項目配置了一個 Github Actions 來自動更新文檔所以在我自己的項目里也增加了類似的配置，除了微軟的項目還有很多社區(qū)開源項目在用，如果你也在做一些 .NET 類庫類的開源項目，可以嘗試一下

docfx 怎么使用可以參考官方文檔，本文主要介紹如何使用 Github Actions 實現(xiàn)自動更新文檔

文檔示例

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

自動更新文檔流程

檢出要使用的用于生成文檔的分支代碼

安裝 docfx 命令行工具，推薦使用 choco 安裝，因為執(zhí)行 build 的 agent 上已經(jīng)安裝了 Chocolatey

使用 docfx 生成文檔

檢出 gh-pages 分支，用于托管文檔的分支

刪除 gh-pages 之前的文件（.git目錄包含git信息，不能刪除）

把第三步操作生成的文檔復(fù)制到 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: Buildruns-on: windows-lateststeps:# Check out the branch that triggered this workflow to the 'source' subdirectory- name: Checkout Codeuses: actions/checkout@v2with:ref: devpath: source- name: install DocFXrun: "& choco install docfx -y"# Run a build- name: Build docsrun: "& docfx ./docfx.json"working-directory: ./source# Check out gh-pages branch to the 'docs' subdirectory- name: Checkout docsuses: actions/checkout@v2with:ref: gh-pagespath: docs# Sync the site- name: Clear docs reporun: Get-ChildItem -Force -Exclude .git | ForEach-Object { Remove-Item -Recurse -Verbose -Force $_ }working-directory: ./docs- name: Sync new contentrun: 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 pushrun: |$ErrorActionPreference = "Continue"git add -Agit diff HEAD --exit-codeif ($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 分支更新了就更新，你也可以根據(jù)需要當 master 分支更新時再更新，修改分支名稱即可

More

現(xiàn)在用的還是 2.x 版本，3.x 版本還沒發(fā)布，3.x版本發(fā)布之后可以直接通過 dotnet tool 來安裝更加方便和可擴展，目前 2.x 使用 choco 來安裝命令行工具，需要依賴 Chocolatey，如果是 dotnet tool 有 dotnet 環(huán)境就可以了，就可以方便很多了

不僅僅是 docfx 生成文檔，你也可以擴展其他類似的需求，使用 Github Actions 實現(xiàn)自動同步，更新

Reference

• https://github.com/dotnet/docfx

• https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html

• https://github.com/WeihanLi/WeihanLi.Npoi

• https://github.com/microsoft/reverse-proxy

總結(jié)

以上是生活随笔為你收集整理的利用 Github Actions 自动更新 docfx 文档的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。