利用 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
自动更新文档流程
- 检出要使用的用于生成文档的分支代码
- 安装 docfx 命令行工具,推荐使用 choco 安装,因为执行 build 的 agent 上已经安装了 Chocolatey
- 使用 docfx 生成文档
- 检出 gh-pages 分支,用于托管文档的分支
- 删除 gh-pages 之前的文件(
.git
目录包含git信息,不能删除) - 把第三步操作生成的文档复制到 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: 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
- 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
利用 Github Actions 自动更新 docfx 文档的更多相关文章
- 利用wsdl.exe自动将wsdl文档转换为C#代码
1.获取完整的wsdl文档 获取下面这个博客中提到的wsdl http://www.cnblogs.com/LCCRNblog/p/3716406.html 将获取到的wsdl放到一个文本中,改后缀( ...
- 用GitHub Actions自动部署Hexo
什么是 GitHub Actions ? GitHub Actions 是一个 CI/CD(持续集成/持续部署)工具,GitHub 于 2018 年 10 月推出,正式版于 2019 年 11 月正式 ...
- Asp.Net Core 轻松学-利用 Swagger 自动生成接口文档
前言 目前市场上主流的开发模式,几乎清一色的前后端分离方式,作为服务端开发人员,我们有义务提供给各个客户端良好的开发文档,以方便对接,减少沟通时间,提高开发效率:对于开发人员来说,编写接口文档 ...
- Asp.Net Core 轻松学系列-5利用 Swagger 自动生成接口文档
目录 前言 结语 源码下载 前言 目前市场上主流的开发模式,几乎清一色的前后端分离方式,作为服务端开发人员,我们有义务提供给各个客户端良好的开发文档,以方便对接,减少沟通时间,提高开发效率:对 ...
- Spring Boot 项目学习 (四) Spring Boot整合Swagger2自动生成API文档
0 引言 在做服务端开发的时候,难免会涉及到API 接口文档的编写,可以经历过手写API 文档的过程,就会发现,一个自动生成API文档可以提高多少的效率. 以下列举几个手写API 文档的痛点: 文档需 ...
- 如何使用 Github Actions 自动抓取每日必应壁纸?
如何白嫖 Github 服务器自动抓取必应搜索的每日壁纸呢? 如果你访问过必应搜索网站,那么你一定会被搜索页面的壁纸吸引,必应搜索的壁纸每日不同,自动更换,十分精美.这篇文章会介绍如何一步步分析出必应 ...
- 试试使用 eolinker 扫描 GitLab 代码注释自动生成 API 文档?
前言: 一般写完代码之后,还要将各类参数注解写入API文档,方便后续进行对接和测试,这个过程通常都很麻烦,如果有工具可以读取代码注释直接生成API文档的话,那会十分方便. 此前一直都是在使用eolin ...
- Spring Boot(九)Swagger2自动生成接口文档和Mock模拟数据
一.简介 在当下这个前后端分离的技术趋势下,前端工程师过度依赖后端工程师的接口和数据,给开发带来了两大问题: 问题一.后端接口查看难:要怎么调用?参数怎么传递?有几个参数?参数都代表什么含义? 问题二 ...
- Spring Boot从入门到精通(十一)集成Swagger框架,实现自动生成接口文档
Swagger是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.Swagger 是一组开源项目,其中主要要项目如下: Swagger-tools:提供各种与S ...
随机推荐
- 自学 Python 到什么程度能找到工作,1300+ 条招聘信息告诉你答案
随着移动互联网的发展以及机器学习等热门领域带给人们的冲击,让越来越多的人接触并开始学习 Python.无论你是是科班出身还是非科班转行,Python 无疑都是非常适合你入门计算机世界的第一门语言,其语 ...
- Spring Cloud Alibaba教程:Nacos
Nacos是什么 Nacos 致力于帮助您发现.配置和管理微服务,它 提供了一组简单易用的特性集,帮助您快速实现动态服务发现.服务配置.服务元数据及流量管理. 注册中心 nacos-server 可以 ...
- Monster Audio 使用教程(一)入门教程 + 常见问题
Monster Audio支持的操作系统: windows 7 64bit 至 windows 10 64bit 受支持的VST: Vst 64bit.Vst3 64bit 受支持的声卡驱动: ASI ...
- Tomcat内部结构、工作原理、工作模式和运行模式
TOMCAT的内部结构 Tomcat是一个基于组件的服务器,它的构成组件都是可配置的,其中最外层的是Catalina servlet容器,其他组件按照一定的格式要求配置在这个顶层容器中.Tomcat的 ...
- 你不知道的Java引用
什么是引用 引用就是保存着一块地址(门牌号)的对象,就像C语言的指针那样,引用可以传递某个数据的地址,如果我们想拿到某一条数据,就要先找到他的地址,然后告诉计算机我去拿这个地址的数据,最后计算机就 ...
- 深度学习论文翻译解析(十一):OverFeat: Integrated Recognition, Localization and Detection using Convolutional Networks
论文标题:OverFeat: Integrated Recognition, Localization and Detection using Convolutional Networks 标题翻译: ...
- Tkinter常用简单操作
截图来自北京尚学堂 手册:http://effbot.org/tkinterbook/ 2020-04-20
- pandas第三方库
# 一维数组与常用操作 import pandas as pd # 设置输出结果列对齐 pd.set_option('display.unicode.ambiguous_as_wide',True) ...
- zabbix 邮件报警和微信报警
# 邮件报警 一.定义邮件发件人 #密码来源 完成操作会看到 二.定义邮件收件人 三.启动动作 #先开启 2.触发操作 3.恢复操作 4.开启发送消息 1.2. 微信报警 一. 首先要注册一个企业微信 ...
- Linux下利用docker搭建elasticsearch(单节点)
1. 拉取镜像 #elasticsearch 6.x和7.x版本有很多不一样需要确认 docker pull docker.elastic.co/elasticsearch/elasticsearch ...