Markdown/reST 文檔DevOps流水線
相信很多朋友都在使用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 的內容
- 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文檔中心地址請點擊 以下地址
更新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就可以了。
【本文為51CTO專欄作者“徐磊”的原創稿件，轉載請通過作者微信公眾號devopshub獲取授權】
