MarkDown/reST 文档发布流水线

时间:2022-09-25 21:02:26

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

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

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

最终发布的效果如下:

MarkDown/reST 文档发布流水线

配置这个流水线也很简单

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

MarkDown/reST 文档发布流水线

以下是 build.sh 的内容

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

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

MarkDown/reST 文档发布流水线

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

MarkDown/reST 文档发布流水线

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

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

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

MarkDown/reST 文档发布流水线

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里面还建立了一个仪表盘来整体显示。

MarkDown/reST 文档发布流水线

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

MarkDown/reST 文档发布流水线

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

http://docs.devopshub.cn/

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

# 使用容器运行sphinx工具,并执行自定义的build.sh脚本
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就可以了。

MarkDown/reST 文档发布流水线

在微信中请点击 阅读原文,谢谢。


MarkDown/reST 文档发布流水线

MarkDown/reST 文档发布流水线的更多相关文章

  1. word文档发布至博客wordpress网站系统

    今天ytkah接到一个需求:将word文档发布到wordpress网站上,因为客户那边习惯用word来编辑文章,想直接将内容导入到wp网站中,其实 Word 已经提供了这样的功能,并且能够保留 Wor ...

  2. Word文档发布到CSDN博客

    目前大部分的博客作者在写博客这件事情上都会遇到以下3个痛点:1.所有博客平台关闭了文档发布接口,用户无法使用Word,Windows Live Writer等工具来发布博客.2.发布到博客或公众号平台 ...

  3. MARKDOWN使用文档

    ISSUE引用 引用当前项目内的ISSUE #1 markdown写法 #1 引用当前命名空间下的其他项目内的ISSUE projectname#1 sofa_ta#1 markdown写法 sofa ...

  4. 开发者福利!百问I.MX6ULL裸机文档发布

    终于等到你,百问科技近600页的100ask_imx6ull裸机文档发布,已经合并到“嵌入式Linux应用开发完全手册第2版_韦东山全系列视频文档全集.pdf(1222页)”,所有人免费下载学习. 本 ...

  5. 拯救你的文档 – 【DevOps敏捷开发动手实验】开源文档发布

    今天上海的天气真是不错,风和日丽.再次来到微软上海紫竹研发中心,心情很是愉快,喜欢这里的大草坪,喜欢这里的工程气氛,更喜欢今天来陪我的小伙伴们. 这次动手实验培训与以往最大的不同就是采用了开源文档的方 ...

  6. 使用Markdown写文档

    转载于:http://blog.csdn.net/xiahouzuoxin/article/details/19752603 Markdown是一种网络书写语言,其目标是实现易读易写,且兼容HTML语 ...

  7. 文档发布工具mkdocs

    mkdocs是Python的一个对 Markdown 友好的文档生成器.,小巧精美. MkDocs is a fast, simple and downright gorgeous static si ...

  8. php markdown 接口文档生成工具 SummerDoc

    2017年9月18日 19:20:22 星期一 因工作需要, 用PHP写了一个管理接口文档的小工具, 下边介绍一下: 浏览器展示的效果: 项目地址:(码云) 例子(http://doc.hearu.t ...

  9. 如何使用Markdown 编写文档

    Markdown 是一种轻量级标记语言,用来编写文本文档,一般后缀名为.md.该语言在 2004 由约翰·格鲁伯(John Gruber)创建. 由于Markdown 语法简单,易读易写,变得越来越通 ...

随机推荐

  1. Linux下编译安装Apache Http Server

    Linux下编译安装Apache Http Server [TOC] 1.下载httpd-2.4.12.tar.bz2 wget http://mirror.bit.edu.cn/apache/htt ...

  2. java判断字符串是否为数字或中文或字母

     个人认为最好的方法 *各种字符的unicode编码的范围:     * 汉字:[0x4e00,0x9fa5](或十进制[19968,40869])     * 数字:[0x30,0x39](或十进制 ...

  3. eclipse中输入@符号自动提示Annotation

    将Eclipse中Content Assist中的Auto activation for java里.的后面加上@符号即可

  4. BZOJ 1257 余数之和sum

    题目链接:http://61.187.179.132/JudgeOnline/problem.php?id=1257 题意:计算sigama(m%i)(1<=i<=n). 思路: 这样就简 ...

  5. hdu 1085

    额    母函数 #include <cstdio> #include <cstring> int a[3],b[3]= {1,2,5}; int c1[10001],c2[1 ...

  6. 【Java】如何访问服务器

    HTTP协议---------->GET.POST.XMLHttpRequest TCP/IP协议 SOAP协议---------->Web Service Server的作用是处理HTT ...

  7. 【小白的java成长系列】——java ide 开发工具eclipse的操作

    今天看了一下自己的博客文章,里面的内容还是比較杂的,有好多技术,有好多语言,都没有突出自己的强项,能够说,从博客里面,看不出我究竟是做哪块的..加上今天被授予了博客准专家勋章,自己想了一下,还是得梳理 ...

  8. css实现隐藏多余溢出文字并显示省略号

    <meta charset="utf-8" /> <style> .txt{ width:200px; border:1px solid #ddd; ove ...

  9. JQuery Rest客户端库

    JQuery Rest https://github.com/jpillora/jquery.rest/ Summary A jQuery plugin for easy consumption of ...

  10. detours express版本的使用

    原文最早发表于百度空间2012-03-21 一.编译lib 1)拷贝它的src文件夹和system.mak文件到VS的VCVARS32.BAT所在的目录下 2)在命令提示符中运行VCVARS32.BA ...