相信很多朋友都在使用Markdown或者restructuredText格式來編寫一些技術(shù)文檔，也會(huì)把這些文檔放在github上分享給社區(qū)。GitHub提供了很好的Markdown格式解析支持，但是這些文檔的閱讀體驗(yàn)并不好，而且有些時(shí)候我們可能只希望給用戶提供可閱讀的html格式而不希望直接把Markdown格式也分享出去。
為了滿足這些要求，我曾經(jīng)使用ReadTheDocs的服務(wù)很長(zhǎng)時(shí)間，因?yàn)樗峁┝撕芷敛⑶疫m配各種屏幕尺寸和手機(jī)的css風(fēng)格。但是我相信很多人也和我一樣，一直都很糾結(jié)它的訪問速度，畢竟服務(wù)器在國(guó)外。后來，我在北京的Azure數(shù)據(jù)中心中自己搭建了ReadTheDocs服務(wù)器，但是發(fā)現(xiàn)在文檔生成和發(fā)布過程中ReadTheDoc必須要下載很多依賴庫(kù)，由于大家都知曉的原因，這讓發(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ā)布的效果如下：