利用 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

自动更新文档流程

  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: 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 分支更新了就更新,你也可以根据需要当 master 分支更新时再更新,修改分支名称即可

More

现在用的还是 2.x 版本,3.x 版本还没发布,3.x版本发布之后可以直接通过 dotnet tool 来安装更加方便和可扩展,目前 2.x 使用 choco 来安装命令行工具,需要依赖 Chocolatey,如果是 dotnet tool 有 dotnet 环境就可以了,就可以方便很多了

不仅仅是 docfx 生成文档,你也可以扩展其他类似的需求,使用 Github Actions 实现自动同步,更新

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

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/news/308191.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

34. 在排序数组中查找元素的第一个和最后一个位置012(二分查找+思路+详解+两种方法)Come Baby!!!!!!!! !

一:题目 给定一个按照升序排列的整数数组 nums,和一个目标值 target。找出给定目标值在数组中的开始位置和结束位置。 如果数组中不存在目标值 target,返回 [-1, -1]。 进阶: 你可以设计并实现时间复杂度为 O(log n) 的算法解…

计算机专业可以报考放射医学吗吗,文科生可以报考医学影像技术专业吗

近期很多文科同学都在疑惑可不可以报考医学影像技术专业,这里有途网小编告诉大家,医学影像技术专业是理科专业,文科生一般来说是不可以报考医学影像技术专业的,但在每年高校招生计划发布的时候也可能会考虑招收文科生的情况&#…

基于PaaS平台的多应用自集成方案之公共数据集成

源宝导读:在明源云“天际”PaaS平台之上,可以构建、部署和运行多个业务应用,并支持多应用分离部署,以提升系统整体的性能和稳定性。本文将介绍多应用自集成解决方案以及相关的实现细节。一、背景1.1、业务场景在明源云“天际”Paa…

vector容器中查找某一元素是否存在(牛逼的vector!!!!!!)

一:前言 当你想要快速查找某一元素是否存在,可以调用该方法 二:步骤 1.写迭代器:vector ::iterator t; 2.调用find方法:t find(v.begin(),v.end(),查找的元素); 3.和v.end()进行比较,如果找…

HTML和css重要的知识点,html 和 css 基础知识点(一)(示例代码)

伪类选择器:伪类是直接在元素后面加“:”,例如a:hover,可直接在css中用而不用在html中像类一样定义,因为是浏览器预先设定好的。a一般顺序是:a:link{} 未访问状态链接a:visited{}已访问状态链接a:hover{}鼠标悬停上时状态还有其他伪类,如first-child对应第一个子元素…

可能是Asp.net Core On host、 docker、kubernetes(K8s) 配置读取的最佳实践

写在前面为了不违反广告法,我竭尽全力,不过“最佳实践”确是标题党无疑,如果硬要说的话 只能是个人最佳实践。问题引出可能很多新手都会遇到同样的问题:我要我的Asp.net Core 应用传统方式直接部署(host),…

33. 搜索旋转排序数组(013)二分查找+思路详解+来干了这杯代码!!!!!!

一&#xff1a;题目 整数数组 nums 按升序排列&#xff0c;数组中的值 互不相同 。 在传递给函数之前&#xff0c;nums 在预先未知的某个下标 k&#xff08;0 < k < nums.length&#xff09;上进行了 旋转&#xff0c;使数组变为 [nums[k], nums[k1], …, nums[n-1], n…

计算机软件在矿井地质中的应用,(完整版)遥感导论知识点整理(梅安新版)

遥感导论知识点整理【题型】一、选择题二、填空题三、名词解释四、简答题五、论述题注意&#xff1a;标注页码的地方比较难理解&#xff0c;希望大家多看看书&#xff0c;看看ppt。【第一章】绪论1、【名】遥感(remote sensing)广义&#xff1a;泛指一切无接触的远距离探测&…

C#实践设计模式原则SOLID

理论跟实践的关系&#xff0c;说远不远&#xff0c;说近不近。能不能把理论用到实践上&#xff0c;还真不好说。通常讲到设计模式&#xff0c;一个最通用的原则是SOLID&#xff1a;S - Single Responsibility Principle&#xff0c;单一责任原则O - Open Closed Principle&…

81. 搜索旋转排序数组 II(014)二分查找+思路+详解+二种做法

一&#xff1a;题目 已知存在一个按非降序排列的整数数组 nums &#xff0c;数组中的值不必互不相同。 在传递给函数之前&#xff0c;nums 在预先未知的某个下标 k&#xff08;0 < k < nums.length&#xff09;上进行了 旋转 &#xff0c;使数组变为 [nums[k], nums[k1…

学校考的计算机三级证书,全国计算机等级考试证书用途

全国计算机等级考试证书用途计算机知识浩如瀚海&#xff0c;即使任何资深人士都不可能精通或熟悉所有的计算机软件&#xff0c;但是为什么他们无论什么软件都能很快就上手会用呢&#xff0c;那是因为本质上任何计算机软件都是C语言之类的编程语言开发出来的&#xff0c;所以我们…

10-4 6-4 查询厂商“D“生产的PC和便携式电脑的平均价格 (10 分)思路+详解+测试用例

前言&#xff1a;测试用表 贴心杰将这个测试表分享给大家 &#xff0c;如果大家做题的时候发现那个点过不去&#xff0c;一定不要直接看别人的博客&#xff0c;先自己测试用例&#xff0c;如果思路也对 &#xff0c;验证数据也对&#xff0c;还有错误 你再看看别人的思路&…

如何校验内存数据的一致性,DynamicExpresso 算是帮上大忙了

一&#xff1a;背景1. 讲故事记的在上一家公司做全内存项目的时候&#xff0c;因为一些关键表会在程序 startup 的时候全量灌入到内存中&#xff0c;但随着时间的推移&#xff0c;内存和数据库的同步偶尔会出现数据差异的情况&#xff0c;伴随着就是运营那边报过来的 bug&#…

qt 实现html 编辑器,基于QT的HTML编辑器的设计与实现.doc

PAGEPAGE 1郑州大学毕业设计(论文)题 目&#xff1a;基于Qt的html编辑器的设计与实现指导教师&#xff1a; 职称&#xff1a;学生姓名&#xff1a; 学号&#xff1a;专 业&#xff1a;院(系)&#xff1a;完成时间&#xff1a; 2012年5月10日2012年5月10日目录TOC \o "1-2&…

临界表储存图的数据(思路+详解+图示)

一&#xff1a;前言 当我们考虑用邻接表储存数据的时候&#xff0c;一定会拿邻接矩阵和其进行比较。邻接矩阵在储存数量较小的数据是耗费的内存是要高于邻接表的。那么我们在做题的时候如果出现内存超限&#xff0c;那就要注意了&#xff0c;可以考虑换用邻接表来储存数据了 …

译 | 在 Azure SQL 上节约成本的八种方法

点击上方关注“汪宇杰博客”原文&#xff1a;John JG Chirapurath翻译&#xff1a;汪宇杰导语当今世界&#xff0c;企业正崭露头角&#xff0c;渴望重整与重建&#xff0c;但仍处于不确定的时期。节约成本并将开支重新分配到最重要的位置与以往一样重要&#xff0c;许多公司将云…

7-2 单源最短路径 (10 分)(思路+详解+邻接表做法)Come Brather!!!!!!!!!!

一&#xff1a;前言 本次题解先展示用邻接矩阵做的&#xff0c;但其会出现内存超限&#xff0c;因为确实是临界矩阵在数据很大的时候相比临界表是耗内存的&#xff0c;但是以前习惯用临界矩阵了&#xff0c;所以一上来就用临界矩阵做了&#xff0c;后来上网查了后知道邻接矩阵…

计算机一级办公软件试题,计算机一级《MS Office》练习题(含答案)

计算机一级《MS Office》练习题(含答案)11.完整的计算机软件指的是__________.A.程序、数据与相应的文档B.系统软件与应用软件C.操作系统与应用软件D.操作系统和办公软件12.在微机的配置中常看到“P42.4G”字样,其中数字“2.4G”表示__________.A.处理器的时钟频率是2.4GHzB.处…

在.NET Core中使用MongoDB明细教程(3):Skip, Sort, Limit, Projections

到目前为止&#xff0c;我们已经讨论了创建文档, 检索文档&#xff0c;现在让我们来研究一下文档排序&#xff0c;指定要跳过或限制返回的文档数量&#xff0c;以及如何进行投影。此篇文章中的实例代码摘录自原文&#xff0c;未像前几篇文章一样进行实际代码的验证。作者&#…

map容器的使用 逆序遍历map容器当中的数据

一&#xff1a;前言 这个逆序遍历是将map容器的迭代器进行了变化&#xff0c;reverse_iterator逆向遍历的迭代器 &#xff0c;它需要 rbegin()和rend()方法指出反向遍历的 起始位置和终止位置。 二&#xff1a;上码演示 #include<bits/stdc.h> using namespace std;in…