zoukankan      html  css  js  c++  java
  • 利用 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 示例

    自动更新文档流程

    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 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 实现自动同步,更新

    Reference

  • 相关阅读:
    IIS配置Asp.net时,出现“未能加载文件或程序集“System.Web.Extensions.Design, Version=1.0.61025.0”
    如何ping测有端口的网站
    职场情况--小领导人品不好,大领导很欣赏我,该不该将小领导的搓事告诉大领导?
    https://www.cnblogs.com/netoxi/p/7258895.html
    java基本数据类型
    不用犹豫什么时候声明实例变量或者拒不变量
    java多线程
    架构考虑
    多线程一共就俩问题:1.线程安全(访问共享数据) 2.线程通信(wait(),notify())
    csrf攻击
  • 原文地址:https://www.cnblogs.com/weihanli/p/docfx-docs-auto-update.html
Copyright © 2011-2022 走看看