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 文件，需要安装插件 Omni​Markup​Previewer。通过 Package Control 安装插件。

1、安装Package Control

同时按住 "Ctrl + ` " 打开 Sublime Text 的控制台，根据 Package Control 安装提示，将相应的安装代码复制到 console：

2、安装插件

同时按住 " Ctrl + Shift + p " 打开命令面板，输入 install 选择 Install Package 选项，然后即可在列表中查询要安装的插件，例如 Omni​Markup​Previewer：

还可以到Github上查看 Omni​Markup​Previewer 的其他安装方式。

安装好 Omni​Markup​Previewer 后，在 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 按钮，即可查看文档：