写shell脚本将文档放到github pages

脚本主要参考了谷歌的polymer团队的一个发布element元素文档的自动上传脚本gh.sh。

利用apidoc在注释里写API文档一文提到过，如果有需求就把文档发布到github pages上，这样子大家开发方便些。

但是，我们都不喜欢干重复的事情，每次我们生成或者编写好文档之后都需要重复的去运行那几行相同的代码将文档更新到github pages？所以，写了一个shell脚本文件，来自动的将文档更新。

注意：这里的脚本只针对前文提到的利用apidoc编写注释文档有效，如果是有不一样的需求的话，可能需要对脚本进行对应的修改才生效。

工作原理

这里实现的原理其实很简单：

• 先将整个项目克隆下来；
• 新建一个独立的分支gh-pages；
• 进入项目，安装相对应的依赖（这里是gulp跟gulp-apidoc）；
• 执行生成文档的命令（gulp apidoc);
• 利用git rm删除无关的文件；
• commit并上传到github；

脚本内容

为了方便起见，这里是直接使用ssh协议的，所以在执行该脚本的时候注意你使用的帐户是否已经配置好了相应的key。

#!/bin/bash -e

# 配置参数
ORIGIN_URL="your_git_repository_url"
LOCAL_DIR="local_dir_name"
TASK_NAME="gulp_task_name"
API_DOC="api_doc_file_name"

# 克隆远程库
git clone $ORIGIN_URL
cd $LOCAL_DIR

# 切换到独立的gh-pages分支
git checkout --orphan gh-pages

# 安装依赖
npm install gulp gulp-apidoc

# 生成/更新apidoc文件
gulp $TASK_NAME

# 删除除了.gitignore的内容
git rm -rf -q .

# 复制文档的内容到根目录
mv $API_DOC/* .

# 删除文档文件夹
rm -rf $API_DOC

# 删除node_modules
rm -rf node_modules

# 上传文档到github
git add -A .
git commit -am 'seed gh-pages'
git push -u origin gh-pages --force

# 退出并删除
cd ..
rm -rf $LOCAL_DIR

上传完毕之后，别忘了在你的github项目的设置里边修改github pages的源(source)为gh-pages branch。

要是想看具体一点的例子的话，可以查看express-example这个例子。