相信很多朋友都在使用Markdown或者reconstructedText格式写一些技术文档，也会把这些文档分享到github上的社区。GitHub提供了很好的markdown格式解析支持，但是这些文档的阅读体验并不好，有时候我们可能只想给用户提供一个可读的html格式，而不是直接分享markdown格式。为了满足这些需求，我长期使用ReadTheDocs这个服务，因为它提供了漂亮的css样式，可以适配各种屏幕尺寸和手机。不过相信很多人和我一样，一直纠结于它的访问速度，毕竟服务器在国外。后来在北京的Azure数据中心自己搭建了ReadTheDocs服务器，但是发现ReadTheDoc在文档生成和发布过程中需要下载很多依赖库。由于众所周知的原因，这使得发布过程非常不稳定。发布失败经常发生。最后决定自己搭建一个类似ReadTheDocs的自动化文档发布管道，实现文档源码签入后一键自动发布。思路很简单，就是利用提供的持续集成CI引擎推送代码后由VSTS自动触发脚本完成文档编译（将structuredText/Markdown格式转换成html格式），并使用FTP上传到web服务器的特定目录，然后上传后的zip包html压缩上传到vsts作为备份。最终发布效果如下：配置这个流水线也很简单1.在VSTS中创建一个git代码库用来签入文档源码，并创建一个文档编译脚本build.sh下面是build.sh的内容sphinx-build-bhtml./docs/./_build/2.在Azure上创建网站，获取ftp上传地址和账号3.在VSTS中创建如下文件Builddefinition本次构建分4步完成，分别是执行build.sh脚本FTP上传到Azure站点发布文档压缩包投递到VSTS4.在VSTS中创建如下github同步构建定义同步githubstatusgitpullhttps://github.com/lean-soft/$(Build.Repository.Name).gitmaster推送到githubgitpushhttps://$(github-token)@github.com/lean-soft/$(Build.Repository.Name).githead:master注意上面我用的是${Build.Repository.Name}替换了代码库的名字，这样我只需要在vsts和github上保持代码库的名字一致，就不用每次都重新修改这个脚本的内容了。DevOpsHub的文档中心现在有5套不同内容的训练实验手册文档。为了跟踪所有这些文档的更新状态，我还在VSTS中构建了一个仪表板，将它们作为一个整体显示。这些文档也会通过上面提到的github同步任务同步到公司的github主页。如果需要这些文档的源码，可以访问：https://github.com/lean-softDevOpsHub文档中心地址请点击以下地址http://docs.devopshub.cn/Update1、我最近改进了这个pipeline并使用docker来运行sphinx工具，这样我就不用在构建服务器上安装python等一系列工具了。脚本如下：#使用容器运行sphinx工具，执行自定义build.sh脚本dockerrun-it-v$(Build.Repository.LocalPath):/documents/--namedocs-build-container-w/documents/--rmdocker-sphinx:1bash./build.shUpdate2，微软最近发布了一个基于Linux的托管构建服务器，所以我不用自己设置构建服务，只需修改构建即可使用HostedLinux。【本文为专栏作家“徐磊”原创稿件，转载请通过作者微信公众号devopshub获得授权】点此查看该作者更多好文
