利用 Github Actions 自動更新 docfx 文件

# 利用 Github Actions 自動更新 docfx 文件 ## Intro docfx 是微軟出品一個 .NET API 文件框架，有一個理念是程式碼即文件，會根據專案程式碼自動生成 API 文件，即使沒有寫任何註釋也會生成 API 文件，也有一些預設的主題可以配置，也可以自定義主題配置，詳細介紹可以參考官方介紹目前也有很多專案在使用 docfx 來生成文件，比如前段時間介紹過的 `Reserver-Proxy` 專案，也是看到了 reservse-proxy 專案配置了一個 Github Actions 來自動更新文件所以在我自己的專案裡也增加了類似的配置，除了微軟的專案還有很多社群開源專案在用，如果你也在做一些 .NET 類庫類的開源專案，可以嘗試一下 docfx 怎麼使用可以參考官方文件，本文主要介紹如何使用 Github Actions 實現自動更新文件 ## 文件示例 ![](https://img2020.cnblogs.com/blog/489462/202008/489462-20200817083043207-2046838401.png) ![](https://img2020.cnblogs.com/blog/489462/202008/489462-20200817083114953-62514374.png) 更多可以參考:

自動更新文件 commit 示例 ![](https://img2020.cnblogs.com/blog/489462/202008/489462-20200817084517857-1045868571.png) ## 自動更新文件流程 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 示例，源連結:

``` yaml 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 "[email protected]" 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 實現自動同步，更新 ## Reference - - - -

利用 Github Actions 自動更新 docfx 文件

利用 Github Actions 自動更新 docfx 文件

C# 利用FTP自動下載xml文件後利用 FileSystemWatcher 監控目錄下文件變化並自動更新數據庫

Asp.Net Core 輕鬆學-利用 Swagger 自動生成介面文件

Pycharm在創建py文件時,自動添加文件頭註釋

利用glob()函數遍歷文件夾

C#利用NPOI逐行更新excel文件數據

Mybatis自動生成Xml文件，針對字段類型為text等會默認產生XXXXWithBlobs的方法問題

利用formdata對象上傳文件時，需要添加的參數

MySql啟動報錯,無法更新PID文件

VS2013利用ajax訪問不了json文件——VS2013配置webconfig識別json文件

Python腳本之利用django---mysql將磁盤文件系統寫入數據庫保存

解決phpstorm ftp自動保存文件問題

集成jenkins自動安裝apk文件

獲得unity 資源中的MD5值，為資源更新配置文件做準備

GitHub在線創建文件夾

pycharm在創建py文件時，自動添加文件頭註釋

Pycharm在創建py文件時,如何自動添加文件頭註釋(類似於鉤子特性)?

pyCharm自動添加文件頭註釋

Python-根據已有的行政區域信息，自動生成exl文件

思科交換機(archive)定時自動備份配置文件到tftp服務器

利用 Github Actions 自動更新 docfx 文件

相關推薦