建站
咨詢
售后
建站咨詢
新聞中心
相信很多朋友都在使用Markdown或者restructedText格式來編寫一些技術(shù)文檔，也會把這些文檔放在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的自動化文檔發(fā)布流水線，實(shí)現(xiàn)文檔源代碼簽入后的一鍵式自動發(fā)布。思路很簡單，就是利用VSTS所提供的 持續(xù)集成CI 引擎，在推送代碼后自動觸發(fā)腳本完成文檔編譯(把restructuredText/Markdown格式轉(zhuǎn)換為html格式)，同時(shí)使用FTP上傳到web服務(wù)器的特定目錄，再把html壓縮后的zip包上傳到vsts作為備份。
最終發(fā)布的效果如下：
配置這個(gè)流水線也很簡單
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)手冊文檔，為了跟蹤所有這些文檔的更新狀態(tài)，我在VSTS里面還建立了一個(gè)儀表盤來整體顯示。
這些文檔通過以上提到的github同步任務(wù)，也會同步到公司的github主頁上，大家如果需要這些文檔的源碼，可以訪問：https://github.com/lean-soft
DevOpsHub文檔中心地址請點(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就可以了。
【本文為專欄作者“徐磊”的原創(chuàng)稿件，轉(zhuǎn)載請通過作者微信公眾號devopshub獲取授權(quán)】
當(dāng)前名稱：Markdown/reST文檔DevOps流水線
網(wǎng)站路徑：http://m.5511xx.com/article/codhoge.html
