使用 flow.ci 快速发布你的项目文档

软件研发的协作过程中，文档是必不可少的一环，有需求文档、接口文档、使用文档等等。当开始写文档时，首先会遇到两个问题：

  • team members 之间如何协作？
  • 文档 OK 后如何分发，去哪里看？如何更新?

很早的时候采用 word+ppt 做文档，然后放到共享服务器（ftp，samba）上，这种方式会有文档锁定和覆盖的问题，几个人的小团队还可以，大不了更新的时喊一嗓子：“我要更新文档了，大家都不要占用某某文件（使用windows共享文档的童鞋应该很熟悉）”。更新完了还要再喊一嗓子。除此之外，由于 word 文件格式（word文件其实是个压缩包，由很多 xml 和其他文件构成）太过于复杂，即便是借助 git 或者 svn 做版本控制，一旦产生冲突，很难通过肉眼合并和解决冲突。

那么如何解决上述问题呢？这篇文章我用 gitbook + flow.ci 进行文档的发布、集成和部署，希望给有需求的同学一些参考。

如何进行文档协作 & 版本控制 （git+markdown）

开发团队使用 git 或 svn 作为协作和版本控制工具已经是很成熟的方案了，当然也可以用于文档，只是word文档本身天然不太适合版本控制，markdown 是一种轻量级的标记语言, 学习简单，上手容易(具体语法参考 http://wowubuntu.com/markdown/) , 配合 git 几乎能做到完美的文档版本控制 。

如何发布文档 （gitbook+nginx）

最好的方式是把文档发布为 web 网站，这样无需安装任何工具即可查看文档，更新时只需更新网站即可。在这里，用 gitbook 将 markdown 文件快速生成为网站。

什么是 gitbook 呢？官网上是这么介绍的:

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

简单来说就是将 markdown 文档转换成 html、pdf、epub 等多种格式，很多开源软件和书籍都是用 gitbook 发布的，
如：Elasticsearch 权威指南、 Docker — 从入门到实践 等。

如果将 markdown 文档生成静态 html 部署到服务器（nginx）上，不仅可以通过浏览器查看，而且一旦更新server，所有人看到的都是最新的文档。

如何将文档进行持续集成 & 部署 （flow.ci）

CI（Continuous Integration）意为 “持续整合”，指代码的持续测试及与其他代码修改的整合与归并。

CD（Continuous Deployment）意为 “持续部署”，指代码与其补丁的持续部署于整个代码库。

拿文档来看，持续部署就是内容的持续测试、与必要修改的归并及部署。在此，部署意为发布。举例来说，“部署文档”是指输出文件被复制于web服务器为人阅览。

关于持续集成、持续部署不是一两句话能说清的，用于实现 持续集成、持续部署的工具链也五花八门，比如：最常见的 jenkins 、TravisCI 等，使用起来配置过于复杂。这篇文章里我将使用自家的持续集成服务 —— flow.ci 来进行文档的集成和部署，仅供参考。

建一个git repo存储文档

首先，建一个git repo存储文档，此处以 flow.ci官方文档 docs.flow.ci 为例, git repo 为

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

目前 flow.ci 支持 github、bitbucket、国内的coding 和 私有部署的Gitlab。只要文档放在以上代码仓库的 git repo 都可以使用 flow.ci 进行集成. 如何在 flow.ci 创建项目可以 参考文档.

在 flow.ci 上创建 flow

接着，在 flow.ci 上建一个flow，语言模板选用 nodejs(使用 gitbook 需要用到node环境)。

同时删除掉 Cache、Install、Test等 step，这几个 step 是为 nodejs 项目提供的，我们此处只需要 nodejs 运行时环境及 npm 工具。

添加自定义脚本step

删除完之后添加自定义脚本step, 如何添加自定义脚本step可参考文档。 此处要添加两个自定义脚本，一个用于安装gitbook，一个用于编译文档并发布。

安装 gitbook 的自定义脚本 step 内容

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

此处的 flow_cmd 是 flow.ci 提供的一个函数,如果执行命令失败会进行重试

生成静态文件 && 部署 的自定义脚本step 内容

script2

if [ "$FLOW_GIT_BRANCH" == "gitbook" ]; then # 只部署 gitbook分支
  source get_commits_from_last.sh
  bash -x ./deploy.sh 
fi;
  • $FLOW_GIT_BRANCH 是一个环境变量，用来存储当前的git分支
  • get_commits_from_last.sh 会获取上次发布的日期以及git commit id
  • deploy.sh会调用gitbook命令编译markdown文档,并在首页head里面添加本次commit id号以及时间戳,并发布到服务器,脚本会为文末放出
  • 由于deploy.sh会将gitbook生成的静态文件使用scp的方式copy到服务器, 所以 服务器必须添加 rsa key 信任 , rsa-key可以在项目的设置页找到，将其添加倒对应user的~/.ssh/authorized_keys中即可

添加邮件通知的step，文档部署成功后触发

Email Sender插件需要三个参数，分别是邮件接受者、邮件主题、邮件内容模板，如下:

email

总结

至此，使用 flow.ci 快速发布文档的步骤已经全部完成。flow.ci 不只是持续集成，持续部署的工具，也帮助我们用自动化的视角审视手头繁琐的工作，将更多的时间用在新鲜事物上。

有任何疑问发邮件到 my@fir.im，分享你的观点:)

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

  • get_commits_from_last.sh
#!/usr/bin/env bash
# usage: sh get_commits_from_last.sh
# 会export 2个环境变量:
#    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 生成静态文件
gitbook build docs dist

# 获取当前时间
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

# 获取当前分支
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\ \<meta name="version" content="production|COMMIT-TAG"\>' ./dist/index.html
sed -i '/author/a\ \<meta http-equiv="last-modified" content="UPDATE-TIME"\>' ./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 <<EOF
ln -s ${DEPLOY_DIR} ${LATEST_DIR}
exit
EOF
echo "########## Deploy $HOST  success ##########"

exit 0
最后编辑于 ：
©著作权归作者所有,转载或内容合作请联系作者
  • 人面猴
    序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
    沈念sama阅读 194,457评论 5赞 459
  • 死咒
    序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
    沈念sama阅读 81,837评论 2赞 371
  • 救了他两次的神仙让他今天三更去死
    文/潘晓璐 我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
    开封第一讲书人阅读 141,696评论 0赞 319
  • 道士缉凶录：失踪的卖姜人
    文/不坏的土叔 我叫张陵，是天一观的道长。 经常有香客问我，道长，这世上最难降的妖魔是什么？ 我笑而不...
    开封第一讲书人阅读 52,183评论 1赞 263
  • 港岛之恋（遗憾婚礼）
    正文 为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
    茶点故事阅读 61,057评论 4赞 355
  • 恶毒庶女顶嫁案：这布局不是一般人想出来的
    文/花漫 我一把揭开白布。 她就那样静静地躺着，像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上，一...
    开封第一讲书人阅读 46,105评论 1赞 272
  • 城市分裂传说
    那天，我揣着相机与录音，去河边找鬼。 笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。 我是一名探鬼主播，决...
    沈念sama阅读 36,520评论 3赞 381
  • 双鸳鸯连环套：你想象不到人心有多黑
    文/苍兰香墨 我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
    开封第一讲书人阅读 35,211评论 0赞 253
  • 万荣杀人案实录
    序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
    沈念sama阅读 39,482评论 1赞 290
  • 护林员之死
    正文 独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 34,574评论 2赞 309
  • 白月光启示录
    正文 我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 36,353评论 1赞 326
  • 活死人
    序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
    沈念sama阅读 32,213评论 3赞 312
  • 日本核电站爆炸内幕
    正文 年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
    茶点故事阅读 37,576评论 3赞 298
  • 男人毒药：我在死后第九天来索命
    文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 28,897评论 0赞 17
  • 一桩弑父案，背后竟有这般阴谋
    文/苍兰香墨 我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 30,174评论 1赞 250
  • 情欲美人皮
    我被黑心中介骗来泰国打工， 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。 一个月前我还...
    沈念sama阅读 41,489评论 2赞 341
  • 代替公主和亲
    正文 我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
    茶点故事阅读 40,683评论 2赞 335

推荐阅读更多精彩内容