MarkDown/reST 文檔發佈流水線

相信不少朋友都在使用Markdown或者restructuredText格式來編寫一些技術文檔，也會把這些文檔放在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文檔中心地址請點擊 如下地址

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就能夠了。

在微信中請點擊 閱讀原文，謝謝。

---