Markdown/reST 文档DevOps流水线

开发 开发工具
自己搭建类似ReadTheDocs的自动化文档发布流水线,实现文档源代码签入后的一键式自动发布。思路很简单,就是利用VSTS所提供的 持续集成CI 引擎,在推送代码后自动触发脚本完成文档编译(把restructuredText/Markdown格式转换为html格式),同时使用FTP上传到web服务器的特定目录,再把html压缩后的zip包上传到vsts作为备份。

相信很多朋友都在使用Markdown或者restructedText格式来编写一些技术文档,也会把这些文档放在github上分享给社区。GitHub提供了很好的Markdown格式解析支持,但是这些文档的阅读体验并不好,而且有些时候我们可能只希望给用户提供可阅读的html格式而不希望直接把Markdown格式也分享出去。

为了满足这些要求,我曾经使用ReadTheDocs的服务很长时间,因为它提供了很漂亮并且适配各种屏幕尺寸和手机的css风格。但是我相信很多人也和我一样,一直都很纠结它的访问速度,毕竟服务器在国外。后来,我在北京的Azure数据中心中自己搭建了ReadTheDocs服务器,但是发现在文档生成和发布过程中ReadTheDoc必须要下载很多依赖库,由于大家都知晓的原因,这让发布过程变的非常不稳定,经常出现发布失败的情况。

最终,我决定自己搭建类似ReadTheDocs的自动化文档发布流水线,实现文档源代码签入后的一键式自动发布。思路很简单,就是利用VSTS所提供的 持续集成CI 引擎,在推送代码后自动触发脚本完成文档编译(把restructuredText/Markdown格式转换为html格式),同时使用FTP上传到web服务器的特定目录,再把html压缩后的zip包上传到vsts作为备份。

最终发布的效果如下:

配置这个流水线也很简单

1. 在VSTS里创建git代码库签入文档源码,并创建文档编译脚本 build.sh

以下是 build.sh 的内容

  1. sphinx-build -b html ./docs/ ./_build/ 

2. 在Azure上创建Website,并获取ftp上传地址和账户

3. 在VSTS中创建以下文档构建定义

这个构建分成4个步骤完成,分别是

  • 执行 build.sh 脚本
  • FTP 上传到Azure站点
  • 发布文档zip包作为交付件到VSTS中

4. 在VSTS中创建以下github同步构建定义

2个步骤

  •  同步github状态
  • git pull https://github.com/lean-soft/$(Build.Repository.Name).git master
  •  推送到github
  • git push https://$(github-token)@github.com/lean-soft/$(Build.Repository.Name).git head:master

注意以上我使用了 ${Build.Repository.Name}替代了代码库的名称,这样我只要在vsts和github上保持代码库名称的一致,就可以不必每次都重新修改这个脚本的内容。

DevOpsHub的文档中心现在已经5套不同内容的培训实验手册文档,为了跟踪所有这些文档的更新状态,我在VSTS里面还建立了一个仪表盘来整体显示。

这些文档通过以上提到的github同步任务,也会同步到公司的github主页上,大家如果需要这些文档的源码,可以访问:https://github.com/lean-soft

DevOpsHub文档中心地址请点击 以下地址

http://docs.devopshub.cn/

更新1,最近我又改进了这个流水线,使用docker来运行sphinx工具,这样我就不必在构建服务器上安装python等一系列的工具了。脚本如下:

  1. # 使用容器运行sphinx工具,并执行自定义的build.sh脚本 
  2. docker run -it -v $(Build.Repository.LocalPath):/documents/ --name docs-build-container -w /documents/ --rm docker-sphinx:1 bash ./build.sh 

更新2,微软最近发布了基于Linux的托管构建服务器,所以我就不必自己搭建构建服务了,只需要修改构建使用 Hosted Linux就可以了。

【本文为51CTO专栏作者“徐磊”的原创稿件,转载请通过作者微信公众号devopshub获取授权】

戳这里,看该作者更多好文

责任编辑:武晓燕 来源: 51CTO专栏
相关推荐

2017-02-28 15:40:30

Docker流水线Azure

2017-03-02 14:12:13

流水线代码Clojure

2021-04-29 08:55:54

GitLabDevOps项目

2013-06-06 09:31:52

2024-01-07 12:47:35

Golang流水线设计模式

2021-11-08 07:41:16

Go流水线编程

2019-11-07 10:02:33

开源开源工具DevOps

2022-07-18 06:05:28

Gitlab流水线

2023-05-10 15:08:00

Pipeline设计模式

2023-08-18 10:24:52

GitLabCI 流水线

2021-06-26 14:22:34

Tekton流水线Kubernetes

2022-01-26 08:12:42

Jenkins开源流水线

2021-06-28 06:32:46

Tekton Kubernetes Clone

2021-06-18 05:48:02

Tekton DevopsKubernetes

2021-12-24 08:02:48

GitLabCI模板库流水线优化

2023-09-27 08:24:49

2012-04-19 11:44:52

iPhone

2021-01-05 08:39:51

容器前端流水线

2018-10-23 16:35:19

华为云

2019-11-07 09:00:39

Jenkins流水线开源
点赞
收藏

51CTO技术栈公众号