相信很多朋友都在使用Markdown或者restructedText格式來編寫一些技術(shù)文檔，也會(huì)把這些文檔放在github上分享給社區(qū)。GitHub提供了很好的Markdown格式解析支持，但是這些文檔的閱讀體驗(yàn)并不好，而且有些時(shí)候我們可能只希望給用戶提供可閱讀的html格式而不希望直接把Markdown格式也分享出去。

為了滿足這些要求，我曾經(jīng)使用ReadTheDocs的服務(wù)很長時(shí)間，因?yàn)樗峁┝撕芷敛⑶疫m配各種屏幕尺寸和手機(jī)的css風(fēng)格。但是我相信很多人也和我一樣，一直都很糾結(jié)它的訪問速度，畢竟服務(wù)器在國外。后來，我在北京的Azure數(shù)據(jù)中心中自己搭建了ReadTheDocs服務(wù)器，但是發(fā)現(xiàn)在文檔生成和發(fā)布過程中ReadTheDoc必須要下載很多依賴庫，由于大家都知曉的原因，這讓發(fā)布過程變的非常不穩(wěn)定，經(jīng)常出現(xiàn)發(fā)布失敗的情況。

最終，我決定自己搭建類似ReadTheDocs的自動(dòng)化文檔發(fā)布流水線，實(shí)現(xiàn)文檔源代碼簽入后的一鍵式自動(dòng)發(fā)布。思路很簡(jiǎn)單，就是利用VSTS所提供的 持續(xù)集成CI 引擎，在推送代碼后自動(dòng)觸發(fā)腳本完成文檔編譯(把restructuredText/Markdown格式轉(zhuǎn)換為html格式)，同時(shí)使用FTP上傳到web服務(wù)器的特定目錄，再把html壓縮后的zip包上傳到vsts作為備份。

最終發(fā)布的效果如下：

配置這個(gè)流水線也很簡(jiǎn)單

1. 在VSTS里創(chuàng)建git代碼庫簽入文檔源碼，并創(chuàng)建文檔編譯腳本 build.sh

以下是 build.sh 的內(nèi)容

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

2. 在Azure上創(chuàng)建Website，并獲取ftp上傳地址和賬戶

3. 在VSTS中創(chuàng)建以下文檔構(gòu)建定義

這個(gè)構(gòu)建分成4個(gè)步驟完成，分別是

• 執(zhí)行 build.sh 腳本
• FTP 上傳到Azure站點(diǎn)
• 發(fā)布文檔zip包作為交付件到VSTS中

4. 在VSTS中創(chuàng)建以下github同步構(gòu)建定義

2個(gè)步驟

•  同步github狀態(tài)
• 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上保持代碼庫名稱的一致，就可以不必每次都重新修改這個(gè)腳本的內(nèi)容。

DevOpsHub的文檔中心現(xiàn)在已經(jīng)5套不同內(nèi)容的培訓(xùn)實(shí)驗(yàn)手冊(cè)文檔，為了跟蹤所有這些文檔的更新狀態(tài)，我在VSTS里面還建立了一個(gè)儀表盤來整體顯示。

這些文檔通過以上提到的github同步任務(wù)，也會(huì)同步到公司的github主頁上，大家如果需要這些文檔的源碼，可以訪問：https://github.com/lean-soft

DevOpsHub文檔中心地址請(qǐng)點(diǎn)擊 以下地址

http://docs.devopshub.cn/

更新1，最近我又改進(jìn)了這個(gè)流水線，使用docker來運(yùn)行sphinx工具，這樣我就不必在構(gòu)建服務(wù)器上安裝python等一系列的工具了。腳本如下：

# 使用容器運(yùn)行sphinx工具，并執(zhí)行自定義的build.sh腳本 
docker run -it -v $(Build.Repository.LocalPath):/documents/ --name docs-build-container -w /documents/ --rm docker-sphinx:1 bash ./build.sh 

更新2，微軟最近發(fā)布了基于Linux的托管構(gòu)建服務(wù)器，所以我就不必自己搭建構(gòu)建服務(wù)了，只需要修改構(gòu)建使用 Hosted Linux就可以了。

【本文為51CTO專欄作者“徐磊”的原創(chuàng)稿件，轉(zhuǎn)載請(qǐng)通過作者微信公眾號(hào)devopshub獲取授權(quán)】

戳這里，看該作者更多好文