作者 | 日期 | 备注 |
---|---|---|
wywincl | 2017/09/27 | [图片上传失败...(image-1b8d4c-1533004225963)] |
基本介绍
文档化工作一直是程序员们不太热爱的事情,特别是文档规范要求很严格,写一篇技术文档就像写论文一样,格式,字体以及自动索引等等,程序员们普遍感到痛不欲生。因此就出现了像Markdown和reStructuredText这样的格式化标记语言,将繁琐的样式自动生成。本文并不是Markdown和reST的入门介绍文章。如需要了解这两种标记语言,请点击单词链接前往学习。
本文主要是讲解如何用持续交付的方法将基于Markdown或者reStructuredText格式的文本文档通过相关的工具(mkdocs
, sphinx-docs
)以静态HTML页面的方式交付给用户。
文档化工作流
![img_0ad51cbc8a6867e474767ec54191065f.png](https://i-blog.csdnimg.cn/blog_migrate/64423e2b88bc2f774566dc0b5f60acc8.png)
如上图所示,我们将基于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效果
![img_bbf003f4cba900ccc4d45923517ea872.png](https://i-blog.csdnimg.cn/blog_migrate/a1534a9cb5448b10b68ec4c9426a17e6.png)
基本样例
下面我们就来以一个基本的例子,来讲解如何将Gitlab或者(gogs,github等版本管理服务)上的文档引入到readthedocs并进行静态页面生成。
创建项目
我们首先创建一个git仓库sphinx-docs-intro,然后进入仓库,用sphinx-quickstart
命令创建sphinx项目, 这里默认为大家对sphinx已有所了解,如果不熟悉这个工具,请点击链接。
![img_d8b974ae224db77be485b4663fafb62d.png](https://i-blog.csdnimg.cn/blog_migrate/05d94717cd89303ee3cab06d28bcebde.png)
编写rst文档
![img_eb09140b21caffa5a0a74a138a0a1e66.png](https://i-blog.csdnimg.cn/blog_migrate/3365a2ff5705ff31b0ab01ba3d0a16bf.png)
如上图所示,我们用rst格式来编写一个基本的使用指南文档。编写完毕以后,就可以将文档提交到gitlab仓库中。
在readthedocs中引入项目
我们通过import a project
按钮, 来引入我们的项目sphinx-docs-intro
![img_a47fffed03916aec27ccef575526819e.png](https://i-blog.csdnimg.cn/blog_migrate/a0e3488a57672300ddbcb51d2bfaf30c.png)
引入完成后,我们需要在管理界面,设置集成钩子。如下图所示。
![img_80b65518da444d73547ec12fe98de920.png](https://i-blog.csdnimg.cn/blog_migrate/1e904656aadb0f265bd8b6140e3715ac.png)
这样,我们就可以通过触发webhook来自动化构建sphinx文档了。
最终效果
![img_5df73878f6849b7339d44e0e7466e52a.png](https://i-blog.csdnimg.cn/blog_migrate/44fb6e24f9d48c36a8bb80f4c246b636.png)
总结
通过上面的介绍,我们就初步搭建了文档的持续交付平台,文档的持续交付也是DevOps的一个方面。为了全面实施DevOps,我们需要加大对人,工具,文化的投入。
交流
大家可以加入DevOps社区群,一起交流学习。
![img_5098930e03a2b970656d6c42a548184d.png](https://i-blog.csdnimg.cn/blog_migrate/9f0cbd63934fae51d6b4c632560ff4f9.png)