利用 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: 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
利用 Github Actions 自动更新 docfx 文档相关推荐
- 用GitHub Actions自动部署Hexo
本文不算原创,是根据参考文档结合自己的需要修改而成,但也非转载和翻译. 老苏一直用 hexo 发博文,发布过程经历了 三个阶段 第一阶段 : 在家里的台式机上发布 hexo ,流程是先把要发布博文的 ...
- 利用CodeBERT,这个VS Code扩展可以自动生成Python文档字符串
点击上方"AI遇见机器学习",选择"星标"公众号 重磅干货,第一时间送达 来自:机器之心 该扩展利用可处理编程语言和自然语言的预训练模型 CodeBERT,实现 ...
- vscode python 自动补全_利用CodeBERT,这个VS Code扩展可以自动生成Python文档字符串...
机器之心报道 编辑:魔王 该扩展利用可处理编程语言和自然语言的预训练模型 CodeBERT,实现快速生成 Python 文档字符串的功能. Visual Studio Code(简称 VS Code) ...
- 如何利用python自动化办公项目_python办公自动化:自动进行word文档处理和排版
上节python办公自动化:自动打开word文档我们一起学会了在python里打开并保存一个word文档.这节我们将会学会如何利用python进行文本处理和将其在word里进行排版等技巧. pytho ...
- 通过 GitHub Actions 自动创建 Github Release
通过 GitHub Actions 自动创建 Github Release Intro 在 GitHub 上维护了几个小的开源项目,每次在发布新版本的时候会创建一个 release,这样可以比较方便的 ...
- 如何使用 Github Actions 自动抓取每日必应壁纸?
Hello world : ) 微信搜「 程序猿阿朗 」.点赞再看,动力无限. 本文 Github.com/niumoo/JavaNotes 和 未读代码博客 已经收录,有很多知识点和系列文章. 如何 ...
- 这个VS Code扩展可以自动生成Python文档字符串
机器之心报道 编辑:魔王 该扩展利用可处理编程语言和自然语言的预训练模型 CodeBERT,实现快速生成 Python 文档字符串的功能. Visual Studio Code(简称 VS Code) ...
- 【接口文档】Django restful framework中自动生成API文档
Django restful framework中自动生成API文档 一.Swagger概述 1.引言 当接口开发完成,紧接着需要编写接口文档.传统的接口文档使用Word编写,or一些接口文档管理平台 ...
- Spring Boot(九)Swagger2自动生成接口文档和Mock模拟数据
一.简介 在当下这个前后端分离的技术趋势下,前端工程师过度依赖后端工程师的接口和数据,给开发带来了两大问题: 问题一.后端接口查看难:要怎么调用?参数怎么传递?有几个参数?参数都代表什么含义? 问题二 ...
最新文章
- 优化汽车仪表板以实现高效渲染
- Python-OpenCV 杂项(二)(三): 鼠标事件、 程序性能的检测和优化
- 使用CAtlRegExp正则表达式检查浮点数输入
- [渝粤教育] 西南交通大学 信号与系统A 参考 资料
- stm32c语言写数码管定时器,使用TIM1产生1秒定时控制数码管显示0-9(STM32_10)
- Monkey随机性能压测初探(一)
- 【操作系统】多道程序的理解
- AndroidStudio_Android使用OkHttp发起Http请求_以及使用时需要注意的点---Android原生开发工作笔记220
- Laravel 学习笔记5.3之 Query Builder 源码解析(下)
- Android的 线性布局,Android布局之LinearLayout线性布局
- linux内核源码分析之虚拟内存映射
- 一维码和二维码开源库zint学习
- 远程连接mscs下oracle,MSCS+FailSafe ORACLE数据库双机集群做HA小结
- 信号在PCB走线中的延迟
- 如何升级MacOS到指定版本
- 水果店圈子:水果店开业前需要做的准备,水果店开业当天要注意哪些问题
- 1638_chdir函数的功能
- 黑客能追回被骗的钱吗
- Chart.js-柱状图分析(参数分析+例图)
- 数字示波器FFT分析
热门文章
- [k8s]metricbeat的kubernetes模块kube-metric模块
- python list对象
- poj3685 二分套二分
- 【高德地图开发2】---配置工程
- event.x,event.clientX,event.offsetX区别
- 在VSCode Remote环境下开发Teams Bot
- android wi-fi_如何在Android手机上查找3G或Wi-Fi速度
- 如何在Safari中查看网页的完整URL
- 干式真空泵原理_如何安装干式墙锚在墙壁上悬挂重物
- div 包裹_如何查看到达之前收到的包裹和邮件