基于gitbook的本地文檔服務(wù)器

常用的文檔框架有g(shù)itbook和sphinx栏账，兩者都支持markdown格式梁钾，語法上略有區(qū)別武学，前者基于nodejs祭往，后者基于python。

對于文檔編寫火窒，gitbook相對來說更容易上手硼补，故選用gitbook方案。

文檔發(fā)布流程

文檔源文件托關(guān)于代碼倉庫gerrit熏矿，文檔開發(fā)者本地編寫完成之后提交到gerrit已骇，jenkins監(jiān)控文檔倉庫的對應(yīng)分支，一旦提交就會促發(fā)Jenkins文檔任務(wù)票编，將源mark文檔編譯為html文件褪储，并發(fā)布到文檔服務(wù)器上。

文檔服務(wù)器流程.jpg

gitbook容器

為了方便遷移慧域，文檔服務(wù)器采用容器化的方式鲤竹。

gitbook dockerfile：

FROM node:10.22.0-slim

ARG VERSION=3.2.3

LABEL version=$VERSION

RUN npm install -g gitbook-cli &&\
    gitbook fetch ${VERSION} &&\
    npm cache clear &&\
    rm -rf /tmp/*

EXPOSE 4000 35729

CMD /usr/local/bin/gitbook serve

Makefile

SHELL := /bin/bash

# docker parameters
DOCKERCMD=$(shell which docker)
DOCKERBUILD=$(DOCKERCMD) build
DOCKERSTOP=$(DOCKERCMD) stop
DOCKERRM=$(DOCKERCMD) rm
DOCKERRMIMAGE=$(DOCKERCMD) rmi
DOCKERPULL=$(DOCKERCMD) pull
DOCKERPUSH=$(DOCKERCMD) push
DOCKERIMASES=$(DOCKERCMD) images
DOCKERSAVE=$(DOCKERCMD) save
DOCKERTAG=$(DOCKERCMD) tag


# docker image 
DOCKERIMAGENAME=gitbook
VERSION=latest
REPOADDR=192.168.3.23/public

# build
CONTAINERNAME_BUILD= user_manual_build
BUILD_CMD=sh -c "gitbook build"
BUILDPATH=$(CURDIR)

# docker run
#CONTAINERNAME_BUILD= user_manual_build
CONTAINERNAME=user_manual
HOST_DOC_PATH=$(CURDIR)
CONTAINER_DOC_PATH=/root/gitbook
PRIVATE_PORT=4000
HOST_PORT=4000
RUN_CMD=sh -c "gitbook serve"


all: build_doc run_doc

build_doc:
  @echo "build user manual doc"
  $(DOCKERCMD) run --rm -v $(BUILDPATH):$(CONTAINER_DOC_PATH) --name $(CONTAINERNAME_BUILD) $(DOCKERIMAGENAME):$(VERSION) $(BUILD_CMD)
  @echo "Build doc done."

run_doc:
  @echo "docker run upms ..."
  $(DOCKERCMD) run -d -v $(HOST_DOC_PATH):$(CONTAINER_DOC_PATH) -p $(HOST_PORT):$(PRIVATE_PORT) --restart=always --name $(CONTAINERNAME) $(DOCKERIMAGENAME):$(VERSION) $(RUN_CMD)

stop:
  @echo "stop upms docker"
  - $(DOCKERSTOP) $(CONTAINERNAME)
  - $(DOCKERRM) $(CONTAINERNAME)

cleanimage:
  @echo "rmi upms images"
  - $(DOCKERRMIMAGE) $(DOCKERIMAGENAME):$(VERSION)
  - $(DOCKERRMIMAGE) $(REPOADDR)/$(DOCKERIMAGENAME):$(VERSION)


pushimage:
  @echo "push upms image to repo"
  $(DOCKERTAG) $(DOCKERIMAGENAME):$(VERSION) $(REPOADDR)/$(DOCKERIMAGENAME):$(VERSION)
  $(DOCKERPUSH) $(REPOADDR)/$(DOCKERIMAGENAME):$(VERSION)
  $(DOCKERRMIMAGE) $(REPOADDR)/$(DOCKERIMAGENAME):$(VERSION)

文檔編譯

通過gitbook容器將文檔源markdown文件，編譯為html文檔昔榴。
在文檔代碼跟目錄中執(zhí)行makefile命令：

make build_doc

或執(zhí)行命令

/usr/bin/docker run --rm -v /root/code/user-manual:/root/gitbook --name user_manual_build gitbook:latest sh -c "gitbook build"

文檔發(fā)布

文檔發(fā)布同樣使用gitbook鏡像運行

在文檔代碼根目錄中執(zhí)行makefiel命令：

make run_doc