大橙子网站建设,新征程启航

为企业提供网站建设、域名注册、服务器等服务

如何利用GithubActions自动更新docfx文档

本篇文章给大家分享的是有关如何利用Github Actions自动更新docfx文档,小编觉得挺实用的,因此分享给大家学习,希望大家阅读完这篇文章后可以有所收获,话不多说,跟着小编一起来看看吧。

成都创新互联公司坚信:善待客户,将会成为终身客户。我们能坚持多年,是因为我们一直可值得信赖。我们从不忽悠初访客户,我们用心做好本职工作,不忘初心,方得始终。十多年网站建设经验成都创新互联公司是成都老牌网站营销服务商,为您提供网站制作、做网站、网站设计、H5技术、网站制作、品牌网站设计、微信平台小程序开发服务,给众多知名企业提供过好品质的建站服务。

利用 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自动更新docfx文档  

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

 

自动更新文档流程

  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"      # 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/*">        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 实现自动同步,更新。

以上就是如何利用Github Actions自动更新docfx文档,小编相信有部分知识点可能是我们日常工作会见到或用到的。希望你能通过这篇文章学到更多知识。更多详情敬请关注创新互联行业资讯频道。


本文题目:如何利用GithubActions自动更新docfx文档
浏览地址:http://dzwzjz.com/article/ihocpe.html
在线咨询
服务热线
服务热线:028-86922220
TOP