常用的文档框架有gitbook和sphinx，两者都支持markdown格式，语法上略有区别，前者基于nodejs，后者基于python。

对于文档编写，gitbook相对来说更容易上手，故选用gitbook方案。

文档发布流程

文档源文件托关于代码仓库gerrit，文档开发者本地编写完成之后提交到gerrit，jenkins监控文档仓库的对应分支，一旦提交就会促发Jenkins文档任务，将源mark文档编译为html文件，并发布到文档服务器上。

文档服务器流程.jpg

gitbook容器

为了方便迁移，文档服务器采用容器化的方式。

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文档。
在文档代码跟目录中执行makefile命令：

make build_doc

或执行命令

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

文档发布

文档发布同样使用gitbook镜像运行

在文档代码根目录中执行makefiel命令：

make run_doc

或执行命令

/usr/bin/docker run -d -v /root/code/user-manual:/root/gitbook -p 4000:4000 --restart=always --name user_manual gitbook:latest sh -c "gitbook serve"