| 作者 | 日期 | 备注 |
|---|---|---|
| wywincl | 2017/09/27 |
基本介绍
文档化工作一直是程序员们不太热爱的事情，特别是文档规范要求很严格，写一篇技术文档就像写论文一样，格式，字体以及自动索引等等，程序员们普遍感到痛不欲生。因此就出现了像Markdown和reStructuredText这样的格式化标记语言，将繁琐的样式自动生成。本文并不是Markdown和reST的入门介绍文章。如需要了解这两种标记语言，请点击单词链接前往学习。
本文主要是讲解如何用持续交付的方法将基于Markdown或者reStructuredText格式的文本文档通过相关的工具(mkdocs, sphinx-docs)以静态HTML页面的方式交付给用户。
文档化工作流
如上图所示，我们将基于Markdown或者reStructuredText格式的文档保存在Gitlab上进行版本管理。通过Gitlab上的webhook钩子来触发一些事件（通知readthedocs服务器自动拉取指定分支的文档并用sphinx或者mkdocs工具进行html生成），这样我们只要本地对文档进行了修改，就可以自动化地将改动呈现给用户，而无需人为干预。
[备注] readthedocs是静态文档托管服务
环境搭建
为了实现上一节图中所示的工作流，我们需要本地搭建Gitlab服务，
readthedocs服务。
容器化环境构建
- 搭建本地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
- 搭建本地readthedocs服务
$> git clone https://github.com/moul/docker-readthedocs.git
$> cd docker-readthedocs
$> docker-compose run --service-ports --rm readthedocs
效果
readthedocs效果
基本样例
下面我们就来以一个基本的例子，来讲解如何将Gitlab或者(gogs,github等版本管理服务)上的文档引入到readthedocs并进行静态页面生成。
创建项目
我们首先创建一个git仓库sphinx-docs-intro，然后进入仓库，用sphinx-quickstart命令创建sphinx项目, 这里默认为大家对sphinx已有所了解，如果不熟悉这个工具，请点击链接。
编写rst文档
如上图所示，我们用rst格式来编写一个基本的使用指南文档。编写完毕以后，就可以将文档提交到gitlab仓库中。
在readthedocs中引入项目
我们通过import a project按钮, 来引入我们的项目sphinx-docs-intro
引入完成后，我们需要在管理界面，设置集成钩子。如下图所示。
这样，我们就可以通过触发webhook来自动化构建sphinx文档了。
最终效果
总结
通过上面的介绍，我们就初步搭建了文档的持续交付平台，文档的持续交付也是DevOps的一个方面。为了全面实施DevOps，我们需要加大对人，工具，文化的投入。
