本文介绍了利用Sphinx、gitee和read the docs构建一个在线文档系统。
-
Sphinx是一个功能强大的文档生成器，具有许多编写技术文档的强大功能
-
Gitee是一个版本管理系统，它比GitHub具有更快的访问速度
-
Read the Docs是一个在线文档托管服务， 你可以从各种版本控制系统中导入文档
1 安装环境
-
Windows系统
-
python3环境
2 Sphinx安装与测试
2.1 基础功能安装
首先是安装Sphinx，在windows的命令行中输入下面的命令
2.2 创建测试Demo
新建一个文件夹用来测试，比如SphinxDemo，进入该文件夹，命令行中执行下面的命令，新建一个Sphinx的项目框架。
然后会有如下的输出，需要根据提示输入项目名称、作者、版本号、语言等信息
2.3 项目文件结构
项目创建完成后，可以看到如下的目录结构：
进入source文件夹，可以看到如下结构：
这里先简单说明一下各个文件的作用：
-
build：生成的文件的输出目录 -
source: 存放文档源文件 -
_static：静态文件目录，比如图片等 -
_templates：模板目录 -
conf.py：进行 Sphinx 的配置，如主题配置等 -
index.rst：文档项目起始文件，用于配置文档的显示结构 -
cmd.bat：这是自己加的脚本文件（里面的内容是‘cmd.exe’）,用于快捷的打开windows的命令行 -
make.bat：Windows 命令行中编译用的脚本 -
Makefile：编译脚本，make 命令编译时用
2.4 普通编译
执行如下指令
会输出如下编译结果：
然后到build/html文件夹下，浏览器打开index.html文件
可以在浏览器中看到测试效果：
2.5 安装autobuild工具
上面使用make html的方式编译，编译完后需要打开html文件来查。
还有一种HTTP服务的方式，可以在浏览器器中通过ip地址来查看，该方式需要安装自动build工具：
然后使用如下编译指令进行编译
编译结果如下：
然后可以到浏览器中，输入127.0.0.1:8000查看效果：
2.6 更改样式主题
这里选用一个较为常用的主题Read the Docs，安装这个主题首先需要在python中进行安装，命令如下：
然后修改conf.py 文件，找到 html_theme 字段，修改为
再次编译，查看效果：
3 修改测试程序
3.1 安装markdown支持工具
如果相要使用markdown格式的文档，还要安装markdown支持工具，命令如下：
若要使用markdown的表格，还要安装：
然后，还要修改conf.py 文件，找到 extensions字段，修改为:
注：支持markdown后，文档文件可以使用markdown格式，但文档的配置文件
index.rst还要使用reST格式
3.2 修改文档显示结构
3.2.1 index文件分析
修改文档结构，需要修改index.rst文件，首先来看一下这个文件中的内容：
-
两个点
..+空格+后面的文本，代表注释（网页上不显示） -
等号线
====+上一行的文本，代表一级标题 -
.. toctree::声明的一个树状结构（Table of Content Tree） -
:maxdepth: 2表示页面的级数最多显示两级 -
:caption: Contents:用于指定标题文本（可以不要） -
最下面的3行是索引和搜索链接（可以先不用管）
3.2.2 修改index文件
修改soure文件夹下的index.rst文件,，这里表示添加了一个Cpp目录，然后Cpp目录下，链接的又一个index文件
然后新建Cpp文件夹，并在该文件夹内新建若干个子类文件夹和一个index.rst文件，我新建的如下图：
然后编辑soure/Cpp文件夹里的index.rst文件，这里表示该目录级别下，又包含了3个子目录，子目录中再次通过index文件来描述子目录中的文档结构：
然后再进入各个子文件夹，添加markdown格式的文档和index.rst文件，这里以01设计模式文件夹为例：
soure/Cpp/01设计模式中的index.rst文件内容如下，这里表示管理了2个文档
具体的文档，如01单例模式.md中，就可以记录学习笔记了，示例如下：
然后就可以编译，查看效果了。
这是主页的效果：
这是文档的效果：
4 项目托管到gitee
以上的操作，只能在本地的浏览器查看文档，若想让所有人都能看到，需要部署到ReadtheDocs展示，在部署之前，要把代码托管到代码托管平台，这里选用gitee，国内使用速度快。
在上传文件之前，先自己写一个.gitignore文件，用于指示编辑的文件（build目录）不上传到代码仓库，.gitignore文件内容如下：
然后使用就是在本地的项目文件夹内使用基本的git指令来将文件上传到仓库：
5 部署到ReadtheDocs展示
选择手动导入一个项目：
将gitee仓库的HTTPS链接复制过来
填写项目名称，填写gitee仓库的HTTPS链接
然后就可以点击Build version进行项目构建了
Build成功后，点击阅读文档即可查看效果
6 搭建过程演示视频