在线文档部署方案：Sphinx + Read the Docs - 李宇琨的博客

前言

Sphinx是一个基于Python的用于创建文档的工具。它最早是用来制作Python语言的帮助文档。具有以下特征：

Sphinx使用reStructuredText作为标记语言，它的优势来自于reStructuredText语言的强大和直接，及其解析和翻译套件Docutils。

对于已经安装有Python的系统，可以直接使用pip安装Sphinx：

pip install sphinx sphinx-autobuild

完成安装之后，可以在命令窗口输入sphinx-build -h来查看sphinx的版本号和该指令的其他控制参数。

在macOS平台下，使用Homebrew安装是更加便捷的方式之一，安装完成后需要将其添加至PATH中：

brew install sphinx-doc
brew link sphinx-doc --force

关于不同平台下更详细的安装说明，可参考Installing Sphinx。

在需要创建文档的目录下，直接在命令行中输入：

sphinx-quickstart

就会进入Sphinx的创建向导，通过回答一系列问题就能够创建一个Sphinx工程的空白模板（确保关于autodoc的选项设置为yes）。

在完成了向导配置之后，运行

make html

就可以生成html形式的文档了，虽然它还是空白的。

还可以使用sphinx-autobuild来自动重载文档。运行下面指令来实现：

sphinx-autobuild . _build/html

如果要想快速开始使用Sphinx，可以参考First Steps with Sphinx或Sphinx初尝。

更加详细的说明文档可参考Sphinx documentation或Sphinx 使用手册。

使用sphinx-quickstart指令将生成包括conf.py在内的配置文件，以及一份主文档文件index.rst。

conf.py文件包含了该sphinx工程的所有配置选项，包括一些无法在sphinx-quickstart向导中进行设置的复杂选项。更加详细的conf.py配置内容可参考The build configuration file。

reStructuredText是一种易于阅读、所见即所得的纯文本标记语言。它非常利于快速创建简单的网页和独立的文档，尤其是程序的参考手册。reStructuredText是专门为了特定应用的扩展性而设计的，它的解析器是Docutils的一个组件。

这篇文章告诉了你为何不要使用Markdown进行文档写作：Why You Shouldn’t Use “Markdown” for Documentation，主要原因有以下几点：

Lack of a standard

Flavors

Lack of Extensibility

Lack of Semantic Meaning

Lock In and Lack of Portability

reStructuredText为用户提供了快速入门指南和参考手册：

Read the Docs是一个基于Sphinx的在线文档托管系统，使得文档完全可搜索且易于查找。它从在线的Subversion、Bazaar、Git或Mercurial仓库获取到基于Sphinx创建的文档代码，生成文档并为用户托管。

Read the Docs是一个开源的项目，可以免费地在GitHub上获取到项目源代码。

在完成文档的创作之后，只需将文档工程托管在GitHub上，并在Read the Docs网站上创建账号导入GitHub中对应的工程，网站就能够自动帮助你进行编译和发布。

前往Getting Started Guide来了解如何在readthedocs上进行文档托管。

同时，readthedocs在GitHub上也有为初学者准备的演示代码，供大家学习使用。