Read the Docs + Sublime Text + Sphinx + Github托管文档
目录：
- 一、Read the Docs简介
- 二、Sublime Text 配置
- 三、Sphinx使用
- 四、连接 Github
一、Read the Docs简介
Read the Docs 是一个软件文档托管平台。源代码是开源的，服务也是免费的。它支持使用 reStructuredText 编写的 Sphinx 文档，并且支持 Subversion，Bazaar，Git 和 Mercurial 等。 Sphinx 是一个文档生成工具，最初是为编写 Python 文档创建的，现在它拥有出色的工具，可以用于各种语言编写的软件项目。reStructuredText 是一个易于阅读的纯文本标记语法和解析器系统。reStructuredText 是对 StructuredText 和 Setext 轻量级标记系统的修订和重新解释。
二、Sublime Text 配置
使用 Sublime Text 编辑器编写 reStructuredText 文件。安装好 Sublime Text 后，为了方便编写 rst 文件，需要安装插件 OmniMarkupPreviewer。通过 Package Control 安装插件。
1、安装Package Control
同时按住 "Ctrl + ` " 打开 Sublime Text 的控制台，根据 Package Control 安装提示，将相应的安装代码复制到 console：
2、安装插件
同时按住 " Ctrl + Shift + p " 打开命令面板，输入 install 选择 Install Package 选项，然后即可在列表中查询要安装的插件，例如 OmniMarkupPreviewer：
还可以到Github上查看 OmniMarkupPreviewer 的其他安装方式。
安装好 OmniMarkupPreviewer 后，在 Windows 平台下，按下Ctrl + Alt + o即可在浏览器中查看编写好的 rst 文档。
三、Sphinx使用
1、安装Sphinx
不同平台的安装方法，请查看Sphinx官网。本文以 Windows 平台为例。
conda install sphinx
2、创建目录
mkdir Pillow_docs_cn
3、运行 sphinx-quickstart
Sphinx 提供了一个工具 sphinx-quickstart，它将生成一个文档源目录并使用默认值填充它。
cd Pillow_docs_cn
sphinx-quickstart
运行后会生成如下文件：
4、reStructuredText 文档构成的 Sphinx 集合的根目录称为源目录(source directory)。 该目录包含 Sphinx 配置文件 conf.py，可以在该文件配置 Sphinx，例如指定如何读取源文件和构建文档等。主文档 index.rst，主文档的主要作用是用作欢迎页，并且包含目录树表(table of contents tree, toctree)的根。
5、定义文档结构
打开 index.rst 文件，可以看到 toctree 指令最初为空，如下所示：
.. toctree::
:maxdepth: 2
添加文档目录内容：
.. toctree::
:maxdepth: 2
installation.rst
handbook/index.rst
reference/index.rst
porting.rst
about.rst
创建文档
7、运行创建工具
sphinx-quickstart 创建了 Makefile 文件和 make.bat 文件。只需运行 make 命令即可。例如：
make html
使用 make 命令可以指定文件格式，上述命令在 build 目录下生成了一个 HTML 文档。
四、连接 Github
可将编写好的 rst 文件上传至 Github，然后从 readthedocs 导入 Github 项目，这样可通过 readthedocs 对文档进行编译、版本控制等。
将 Github 账号与 readthedocs 账号关联后，即可导入 Github 项目：
点击 Import a Project 按钮，即可看到 Github 项目列表，选择项目导入，对文档进行操作：
点击 Builds 按钮，对文档进行编译，编译成功后点击 View Docs 按钮，即可查看文档：
