基本介绍

文档化工作一直是程序员们不太热爱的事情，特别是文档规范要求很严格，写一篇技术文档就像写论文一样，格式，字体以及自动索引等等，程序员们普遍感到痛不欲生。因此就出现了像Markdown和reStructuredText这样的格式化标记语言，将繁琐的样式自动生成。本文并不是Markdown和reST的入门介绍文章。如需要了解这两种标记语言，请点击单词链接前往学习。
本文主要是讲解如何用持续交付的方法将基于Markdown或者reStructuredText格式的文本文档通过相关的工具(mkdocs, sphinx-docs)以静态HTML页面的方式交付给用户。

文档化工作流

文档化持续交付工作流

如上图所示，我们将基于Markdown或者reStructuredText格式的文档保存在Gitlab上进行版本管理。通过Gitlab上的webhook钩子来触发一些事件（通知readthedocs服务器自动拉取指定分支的文档并用sphinx或者mkdocs工具进行html生成），这样我们只要本地对文档进行了修改，就可以自动化地将改动呈现给用户，而无需人为干预。

[备注] readthedocs是静态文档托管服务

环境搭建

为了实现上一节图中所示的工作流，我们需要本地搭建Gitlab服务，
readthedocs服务。

容器化环境构建

1. 搭建本地Gitlab服务

$>sudo docker run --detach \
--hostname gitlab.example.com \
--publish 443:443 --publish 80:80 --publish 22:22 \
--name gitlab \
--restart always \
--volume /srv/gitlab/config:/etc/gitlab \
--volume /srv/gitlab/logs:/var/log/gitlab \
--volume /srv/gitlab/data:/var/opt/gitlab \
gitlab/gitlab-ce:latest

1. 搭建本地readthedocs服务

$> git clone https://github.com/moul/docker-readthedocs.git
$> cd docker-readthedocs 
$> docker-compose run --service-ports --rm readthedocs

效果

readthedocs效果

readthedocs

基本样例

下面我们就来以一个基本的例子，来讲解如何将Gitlab或者(gogs,github等版本管理服务)上的文档引入到readthedocs并进行静态页面生成。

创建项目

我们首先创建一个git仓库sphinx-docs-intro，然后进入仓库，用sphinx-quickstart命令创建sphinx项目, 这里默认为大家对sphinx已有所了解，如果不熟悉这个工具，请点击链接。

sphinx-docs-intro

编写rst文档

turtorial

如上图所示，我们用rst格式来编写一个基本的使用指南文档。编写完毕以后，就可以将文档提交到gitlab仓库中。

在readthedocs中引入项目

我们通过import a project按钮, 来引入我们的项目sphinx-docs-intro

import project

引入完成后，我们需要在管理界面，设置集成钩子。如下图所示。

webhook

这样，我们就可以通过触发webhook来自动化构建sphinx文档了。

最终效果

效果

总结

通过上面的介绍，我们就初步搭建了文档的持续交付平台，文档的持续交付也是DevOps的一个方面。为了全面实施DevOps，我们需要加大对人，工具，文化的投入。

交流

大家可以加入DevOps社区群，一起交流学习。

DevOps社区