常用的文档框架有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"
网友评论