使用gitbook+gitlab构建文档中心

文档中心

实现要求

在gitlab上创建一个project "document",用于指定需要通过gitbook构建的project文档,实现自动拉取gitlab上需要构建的project,并通过gitbook对每个project文档生成一本书。其中document中创建一个config的配置文件,格式如下

1
2
3
#  git项目路径                          项目分支        文档名称            文档分类路径
git@gitlab.xxx.com:<project1>.git master <document1_name> 项目文档
git@gitlab.xxx.com:<project2>.git master <document2_name> 接口文档

实现过程

通过以下shell脚本将获取config文件的配置,并自动循环拉取gitlab中的指定文档,若文档有更新则自动通过gitbook build构建成一本书,并通过rsync同步到”文档分类路径”中指定的路径下,通过nginx发布web页面(避免build过程中导致页面无法访问)。同时,在构建每一本书的时候会自动按照文档分类将该书的链接添加到summary/README.md文件中,用于生成首页。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
#!/bin/sh
DOCUMENT_CONFIG_DIR=gitbook
DOCUMENT_REPO=git@gitlab.leucs.com:server/document/gitbook.git

NUM=1
DOCUMENT_GIT_DIR=`pwd`
DOCUMENT_BUILD_DIR="/home/gitlab-runner/gitbook_build"
DOCUMENT_DIR="/home/gitlab-runner/gitbook"

index_init(){
> $DOCUMENT_GIT_DIR/summary/README.md
for i in `grep -v ^"#" $DOCUMENT_CONFIG_DIR/config|grep -v ^"$"|awk '{print $NF}'|uniq`
do
echo "# $i" >> $DOCUMENT_GIT_DIR/summary/README.md
echo "" >> $DOCUMENT_GIT_DIR/summary/README.md
done
}

books_build_sync(){
cd $DOCUMENT_GIT_DIR
for dir in `grep -v ^"#" $DOCUMENT_CONFIG_DIR/config|grep -v ^"$" |awk '{print $1}'|awk -F / '{print $NF}'|sed 's/.git//'`
do
cd $DOCUMENT_GIT_DIR
git_repo=`grep -w ${dir}.git $DOCUMENT_CONFIG_DIR/config | awk '{print $1}'`
branch=`grep -w ${dir}.git $DOCUMENT_CONFIG_DIR/config | awk '{print $2}'`
title=`grep -w ${dir}.git $DOCUMENT_CONFIG_DIR/config | awk '{print $3}'`
location=`grep -w ${dir}.git $DOCUMENT_CONFIG_DIR/config | awk '{print $4}'`
domain=`grep -w ${dir}.git $DOCUMENT_CONFIG_DIR/config |awk -F [@:] '{print $2}'`
project=`grep -w ${dir}.git $DOCUMENT_CONFIG_DIR/config |awk '{print $1}'|awk -F: '{print $2}'| sed 's/.git//'`

if [ ! -d "$dir" ];then
git clone -b $branch $git_repo
else
cd $dir && git pull origin
fi
###sh book_gen.sh
cat > $DOCUMENT_GIT_DIR/$dir/book.json <<EOF
{
"title": "$dir",
"description": "$dir",
"author": "xxx",
"output.name": "site",
"language": "zh-hans",
"gitbook": "3.2.3",
"root": ".",
"links": {
"sidebar": {
"Home": "http://docs.xxx.com"
}
},
"plugins": [
"-lunr",
"-highlight",
"-livereload",
"-search",
"search-plus",
"highlight-code",
"alerts",
"terminal",
"code",
"anchor-navigation-ex",
"expandable-chapters",
"edit-link",
"splitter"
],
"pluginsConfig": {
"terminal": {
"copyButtons": false,
"fade": true,
"style": "flat"
},
"anchor-navigation-ex": {
"showLevel": false
},
"code": {
"copyButtons": true
},
"fontSettings": {
"theme": "white",
"family": "msyh",
"size": 2
},
"edit-link": {
"base": "http://$domain/$project/edit/$branch",
"label": "编辑此页"
}
}
}
EOF


export BOOK${NUM}_GIT_DIR="$DOCUMENT_GIT_DIR/$dir"
export BOOK${NUM}_BUILD_DIR="$DOCUMENT_BUILD_DIR/$location/$dir"
export BOOK${NUM}_DIR="$DOCUMENT_DIR/$location/$dir"

if eval [ ! -d '$'"BOOK${NUM}_BUILD_DIR" ];then
eval mkdir -p '$'"BOOK${NUM}_BUILD_DIR"
fi
if eval [ ! -d '$'"BOOK${NUM}_DIR" ];then
eval mkdir -p '$'"BOOK${NUM}_DIR"
fi

# build book if found new files appear in 6 seconds
export change${NUM}=`eval find '$'"BOOK${NUM}_GIT_DIR" -type f -mmin -0.1 ! -name "SUMMARY.md" ! -name "FETCH_HEAD" ! -name book.json |wc -l`
if eval [ '$'"change${NUM}" -ne 0 ];then
eval cd '$'"BOOK${NUM}_GIT_DIR"
mv SUMMARY.md SUMMARY.md_bak > /dev/null 2>&1
/usr/bin/book sm

# delete catalog of node_module for SUMMARY.md
line1=`grep -n "\- Node Modules" SUMMARY.md |head -1 |awk -F: '{print $1}'`
line2=`grep -n node_modules SUMMARY.md |tail -1|awk -F: '{print $1}'`
if [ -n "$line1" -a -n "$line2" ];then
/usr/bin/sed -i "${line1},${line2}d" SUMMARY.md
fi

# add CHANGELOG
/bin/git log --graph -n 50 --pretty="[%cd] - <%an> %s" > CHANGELOG.md
sed -i '/* \[CHANGELOG](CHANGELOG.md)/d' SUMMARY.md
sed -i "2a * [CHANGELOG](CHANGELOG.md)" SUMMARY.md

# copy node_modules if it is not exist
if eval [ ! -d "node_modules" ];then
/bin/cp -rp ~/node_modules/ .
fi

# build book and sync to web for nginx
eval rm -rf '$'"BOOK${NUM}_BUILD_DIR"
echo -e "\033[33m==== Begin to build $dir[$title] ====\033[0m"
eval /usr/bin/gitbook build '$'"BOOK${NUM}_GIT_DIR" '$'"BOOK${NUM}_BUILD_DIR"

echo -e "\033[33m==== Begin to sync $dir[$title] ====\033[0m"
eval /usr/bin/rsync -avz --delete '$'"BOOK${NUM}_BUILD_DIR/" '$'"BOOK${NUM}_DIR" > /dev/null 2>&1
else
echo -e "\033[32m==== Skip to build $dir[$title] ====\033[0m"
fi

# add catalog to index according to class for book
line_title=`grep -n "# $location" $DOCUMENT_GIT_DIR/summary/README.md |awk -F: '{print $1}'`
sed -i "${line_title}a - [$title]($location/$dir/index.html)" $DOCUMENT_GIT_DIR/summary/README.md

NUM=`expr $NUM + 1`
done
}

summary_build(){
echo -e "\033[33m==== Begin to build summary ====\033[0m"
cd $DOCUMENT_GIT_DIR
/usr/bin/sed -i 's/.md/.html/' ./summary/README.md
/usr/bin/sed -i '$a # gitbook自动构建情况' summary/README.md
/usr/bin/sed -i '$a - [构建详情](http://jenkins-develop.xxx.com/job/gitbook/lastBuild/console)' summary/README.md

/usr/bin/gitbook build ./summary $DOCUMENT_DIR/summary/
sed -i 's/index.html/index.html" target="blank"/' $DOCUMENT_DIR/summary/index.html
ln -sf $DOCUMENT_DIR/summary/* $DOCUMENT_DIR/
}


index_init
books_build_sync
summary_build

实现效果

1
2
3
4
5
6
7
#  git项目路径                                    项目分支        文档名称            文档分类路径
git@gitlab.xxx.com:server/smServer-API.git master smServer-API 接口文档
git@gitlab.xxx.com:server/openapi.git master YMS-OpenAPI 接口文档
git@gitlab.xxx.com:server/Apollo-SS-API.git master 会议管理 接口文档
git@gitlab.xxx.com:server/conference-apidoc.git master Web后端接口文档 接口文档
git@gitlab.xxx.com:server-ss/common.git master SIP文档 模块文档
git@gitlab.xxx.com:server/document_example.git master 文档项目说明 其它文档

坚持原创技术分享,您的支持将鼓励我继续创作!
0%