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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

生成靜態(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 是一個環(huán)境變量，用來存儲當(dāng)前的git分支

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

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

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

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

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

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

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

get_commits_from_last.sh

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

set -e

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

# 從首頁html中提取上次 部署的ID 和 部署時間
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)前時間
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)

# 將本次部署的時間和COMMIT ID 嵌入倒首頁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

# 開始部署
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 <