摘要：如何發(fā)布文檔最好的方式是把文檔發(fā)布為網(wǎng)站，這樣無(wú)需安裝任何工具即可查看文檔，更新時(shí)只需更新網(wǎng)站即可。在這里，用將文件快速生成為網(wǎng)站。拿文檔來(lái)看，持續(xù)部署就是內(nèi)容的持續(xù)測(cè)試與必要修改的歸并及部署。在此，部署意為發(fā)布。

軟件研發(fā)的協(xié)作過(guò)程中，文檔是必不可少的一環(huán)，有需求文檔、接口文檔、使用文檔等等。當(dāng)開(kāi)始寫(xiě)文檔時(shí)，首先會(huì)遇到兩個(gè)問(wèn)題：

team members 之間如何協(xié)作？

文檔 OK 后如何分發(fā)，去哪里看？如何更新?

很早的時(shí)候采用 word+ppt 做文檔，然后放到共享服務(wù)器（ftp，samba）上，這種方式會(huì)有文檔鎖定和覆蓋的問(wèn)題，幾個(gè)人的小團(tuán)隊(duì)還可以，大不了更新的時(shí)喊一嗓子：“我要更新文檔了，大家都不要占用某某文件（使用windows共享文檔的童鞋應(yīng)該很熟悉）”。更新完了還要再喊一嗓子。除此之外，由于 word 文件格式（word文件其實(shí)是個(gè)壓縮包，由很多 xml 和其他文件構(gòu)成）太過(guò)于復(fù)雜，即便是借助 git 或者 svn 做版本控制，一旦產(chǎn)生沖突，很難通過(guò)肉眼合并和解決沖突。

那么如何解決上述問(wèn)題呢？這篇文章我用 gitbook + flow.ci 進(jìn)行文檔的發(fā)布、集成和部署，希望給有需求的同學(xué)一些參考。

開(kāi)發(fā)團(tuán)隊(duì)使用 git 或 svn 作為協(xié)作和版本控制工具已經(jīng)是很成熟的方案了，當(dāng)然也可以用于文檔，只是word文檔本身天然不太適合版本控制，markdown 是一種輕量級(jí)的標(biāo)記語(yǔ)言, 學(xué)習(xí)簡(jiǎn)單，上手容易(具體語(yǔ)法參考 http://wowubuntu.com/markdown/) , 配合 git 幾乎能做到完美的文檔版本控制 。

最好的方式是把文檔發(fā)布為 web 網(wǎng)站，這樣無(wú)需安裝任何工具即可查看文檔，更新時(shí)只需更新網(wǎng)站即可。在這里，用 gitbook 將 markdown 文件快速生成為網(wǎng)站。

什么是 gitbook 呢？官網(wǎng)上是這么介紹的:

GitBook is a modern publishing toolchain. Making both writing and collaboration easy.

簡(jiǎn)單來(lái)說(shuō)就是將 markdown 文檔轉(zhuǎn)換成 html、pdf、epub 等多種格式，很多開(kāi)源軟件和書(shū)籍都是用 gitbook 發(fā)布的，
如：Elasticsearch 權(quán)威指南、 Docker — 從入門(mén)到實(shí)踐 等。

如果將 markdown 文檔生成靜態(tài) html 部署到服務(wù)器（nginx）上，不僅可以通過(guò)瀏覽器查看，而且一旦更新server，所有人看到的都是最新的文檔。

CI（Continuous Integration）意為 “持續(xù)整合”，指代碼的持續(xù)測(cè)試及與其他代碼修改的整合與歸并。
CD（Continuous Deployment）意為 “持續(xù)部署”，指代碼與其補(bǔ)丁的持續(xù)部署于整個(gè)代碼庫(kù)。

拿文檔來(lái)看，持續(xù)部署就是內(nèi)容的持續(xù)測(cè)試、與必要修改的歸并及部署。在此，部署意為發(fā)布。舉例來(lái)說(shuō)，“部署文檔”是指輸出文件被復(fù)制于web服務(wù)器為人閱覽。

關(guān)于持續(xù)集成、持續(xù)部署不是一兩句話(huà)能說(shuō)清的，用于實(shí)現(xiàn) 持續(xù)集成、持續(xù)部署的工具鏈也五花八門(mén)，比如：最常見(jiàn)的 jenkins 、TravisCI 等，使用起來(lái)配置過(guò)于復(fù)雜。這篇文章里我將使用自家的持續(xù)集成服務(wù) —— flow.ci 來(lái)進(jìn)行文檔的集成和部署，僅供參考。

首先，建一個(gè)git repo存儲(chǔ)文檔，此處以 flow.ci官方文檔 docs.flow.ci 為例, git repo 為

git@github.com:FIRHQ/flow.ci.git

目前 flow.ci 支持 github、bitbucket、國(guó)內(nèi)的coding 和 私有部署的Gitlab。只要文檔放在以上代碼倉(cāng)庫(kù)的 git repo 都可以使用 flow.ci 進(jìn)行集成. 如何在 flow.ci 創(chuàng)建項(xiàng)目可以 參考文檔.

接著，在 flow.ci 上建一個(gè)flow，語(yǔ)言模板選用 nodejs(使用 gitbook 需要用到node環(huán)境)。

同時(shí)刪除掉 Cache、Install、Test等 step，這幾個(gè) step 是為 nodejs 項(xiàng)目提供的，我們此處只需要 nodejs 運(yùn)行時(shí)環(huán)境及 npm 工具。

刪除完之后添加自定義腳本step, 如何添加自定義腳本step可參考文檔。 此處要添加兩個(gè)自定義腳本，一個(gè)用于安裝gitbook，一個(gè)用于編譯文檔并發(fā)布。

安裝 gitbook 的自定義腳本 step 內(nèi)容

flow_cmd "npm install gitbook-cli -g" --echo --retry --assert

此處的 flow_cmd 是 flow.ci 提供的一個(gè)函數(shù),如果執(zhí)行命令失敗會(huì)進(jìn)行重試

生成靜態(tài)文件 && 部署 的自定義腳本step 內(nèi)容

if [ "$FLOW_GIT_BRANCH" == "gitbook" ]; then # 只部署 gitbook分支
  source get_commits_from_last.sh
  bash -x ./deploy.sh 
fi;

$FLOW_GIT_BRANCH 是一個(gè)環(huán)境變量，用來(lái)存儲(chǔ)當(dāng)前的git分支

get_commits_from_last.sh 會(huì)獲取上次發(fā)布的日期以及git commit id

deploy.sh會(huì)調(diào)用gitbook命令編譯markdown文檔,并在首頁(yè)head里面添加本次commit id號(hào)以及時(shí)間戳,并發(fā)布到服務(wù)器,腳本會(huì)為文末放出

由于deploy.sh會(huì)將gitbook生成的靜態(tài)文件使用scp的方式copy到服務(wù)器, 所以 服務(wù)器必須添加 rsa key 信任 , rsa-key可以在項(xiàng)目的設(shè)置頁(yè)找到，將其添加倒對(duì)應(yīng)user的~/.ssh/authorized_keys中即可

Email Sender插件需要三個(gè)參數(shù)，分別是郵件接受者、郵件主題、郵件內(nèi)容模板，如下:

至此，使用 flow.ci 快速發(fā)布文檔的步驟已經(jīng)全部完成。flow.ci 不只是持續(xù)集成，持續(xù)部署的工具，也幫助我們用自動(dòng)化的視角審視手頭繁瑣的工作，將更多的時(shí)間用在新鮮事物上。

有任何疑問(wèn)發(fā)郵件到 my@fir.im，分享你的觀點(diǎn):)

附上所有 step 中涉及的腳本：

get_commits_from_last.sh

#!/usr/bin/env bash
# usage: sh get_commits_from_last.sh
# 會(huì)export 2個(gè)環(huán)境變量:
#    DEPLOY_DIFF 與上次部署的時(shí)間差
#    DEPLOY_LOG  與上次部署的變化

set -e

STAGE="docs"
URL="${STAGE}.flow.ci"
HTML=`eval curl -sS ${URL}` # 獲取首頁(yè)html

# 從首頁(yè)html中提取上次 部署的ID 和 部署時(shí)間
LAST_ID=`echo $HTML | awk "match($0, /-[0-9a-f]{7}/) { print substr( $0, RSTART+1, RLENGTH-1 )}"`
LAST_TIME=`echo $HTML | awk "match($0, /[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}/) { print substr( $0, RSTART, RLENGTH )}"`"Z"


FMT="%Y-%m-%dT%H:%M:%SZ"
currDate=`date -u +"$FMT"`

if [[ `uname` == "Darwin" ]]; then
  ts=$(date -j -f "$FMT" "${currDate}" "+%s")
  ts2=$(date -j -f "$FMT" "${LAST_TIME}" "+%s")
else
  ts=$(date --date="${currDate}" +"%s")
  ts2=$(date --date="${LAST_TIME}" +"%s")
fi

(( diff=(ts-ts2)/60 ))

export DEPLOY_DIFF=$diff
echo "Last $1 version : $LAST_ID @ ${LAST_TIME} (${DEPLOY_DIFF} minutes ago)"
echo "-----------------------------------------"
export DEPLOY_LOG=`git log --oneline $LAST_ID..HEAD`
echo "${DEPLOY_LOG}"

deploy.sh

#!/bin/bash

set -e

# VARS
DEPLOY_TIME=`date +%Y%m%d%H%M%S`
REMOTE_DIR="/var/www/flow-doc"
RELEASE_DIR="${REMOTE_DIR}/release"
DEPLOY_DIR="${RELEASE_DIR}/${DEPLOY_TIME}"
LATEST_DIR="${REMOTE_DIR}/latest"

TARGET=prod
USER=deploy # 需添加 rsa key 信任
HOST="此處修改為server的ip"
PORT=22 # ssh端口

# 使用gitbook 生成靜態(tài)文件
gitbook build docs dist

# 獲取當(dāng)前時(shí)間
FMT="%Y-%m-%dT%H:%M:%SZ"
currDate=`date -u +"$FMT"`
if [[ `uname` == "Darwin" ]]; then
  ts=$(date -j -f "$FMT" "${currDate}" "+%s") 
else
  ts=$(date --date="${currDate}" +"%s")
fi

# 獲取當(dāng)前分支
branch=$(git rev-parse --abbrev-ref HEAD)
if [ -n "$FLOW_GIT_BRANCH" ] ; then
  branch=$FLOW_GIT_BRANCH
fi

# 獲取commit log
commit=$(git rev-parse --short HEAD)

# 將本次部署的時(shí)間和COMMIT ID 嵌入倒首頁(yè)html中
sed -i "/author/a " ./dist/index.html
sed -i "/author/a " ./dist/index.html

sed -i "s/COMMIT-TAG/${branch}-${commit}/g" ./dist/index.html
sed -i "s/UPDATE-TIME/${currDate}/g" ./dist/index.html

# 開(kāi)始部署
echo "########## Deploy to ${TARGET} ##########"
ssh ${USER}@${HOST} -p ${PORT} "mkdir -p ${DEPLOY_DIR}"
ssh ${USER}@${HOST} -p ${PORT} "rm -rfv ${LATEST_DIR}"

scp -P ${PORT}  -rv ./dist/* ${USER}@${HOST}:${DEPLOY_DIR}
ssh ${USER}@${HOST} -p ${PORT} bash -x <