使用 Sphinx 给 Python 项目生成【Read the Docs】在线文档

1. Sphinx 和 Read the Docs

1.1 Sphinx

Sphinx 是一个强大的文档生成器，具有许多用于编写技术文档的强大功能，包括：

• 维护一份源文档，生成网页，可打印的PDF，用于电子阅读器（ePub）的文档等
• 支持 reStructuredText 或 Markdown 编写文档
• 被广泛使用的代码文档系统
• 代码示例语法高亮
• 活跃的官方和第三方扩展生态

1.2 Read the Docs

“Read the Docs” 提供自动构建，版本控制和在线托管，来简化软件文档的发布和管理。它使用 Sphinx 生成 html 静态页面，通过 github 账户授权，在本地项目 push 到 github 仓库时，自动完成文档的生成和在线更新。

1.3 两者关系

可以简单认为 Sphinx 是一个独立的文档生成工具，可以支持不同的主题；而 Read the Docs 是一个免费的在线文档托管平台，它使用 Sphinx 作为文档生成工具，并提供自己的主题。两者关系类似于 jekyll 和 GitHub Pages。

2. 安装

2.1 安装 Sphinx

pip install sphinx

2.2 安装 Read the Docs 主题

pip install sphinx_rtd_theme

* 2.3 安装 Sphinx Markdown 扩展

默认使用 reStructuredText (.rst) 编写文档，如需支持 Markdown (.md)，需要安装此扩展。

pip install recommonmark

3. 给已有项目添加文档

以笔者真实托管在 GitHub 上的项目 imgkernel 为例。读者以自己实际项目对相关部分做修改，下文不再单独讲述。

3.1 在项目根目录创建 docs 目录

克隆项目：