文档持续交付

  1. 云栖社区>
  2. 博客>
  3. 正文

文档持续交付

wywincl_wy 2017-09-27 11:02:00 浏览757
作者 日期 备注
wywincl 2017/09/27 [图片上传失败...(image-1b8d4c-1533004225963)]

基本介绍

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

文档化工作流

img_0ad51cbc8a6867e474767ec54191065f.png
文档化持续交付工作流

如上图所示,我们将基于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效果

img_bbf003f4cba900ccc4d45923517ea872.png
readthedocs

基本样例

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

创建项目

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

img_d8b974ae224db77be485b4663fafb62d.png
sphinx-docs-intro

编写rst文档

img_eb09140b21caffa5a0a74a138a0a1e66.png
turtorial

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

在readthedocs中引入项目

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

img_a47fffed03916aec27ccef575526819e.png
import project

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


img_80b65518da444d73547ec12fe98de920.png
webhook

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

最终效果

img_5df73878f6849b7339d44e0e7466e52a.png
效果

总结

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

交流

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


img_5098930e03a2b970656d6c42a548184d.png
DevOps社区