Sphinx：Python 文档生成的老牌工具

Sphinx 在 GitHub 上已经拿到 7,866 Star 了。

这个项目最初为 Python 而生，后来成了整个 Python 生态里最主流的文档生成工具。它用 reStructuredText 作为标记语言，输出 HTML、PDF、EPUB、纯文本、TeX、man page 等多种格式。很多开发者认识它，是因为 Read the Docs 上几乎每个 Python 项目的文档都是用 Sphinx 生成的。

1、为什么用 Sphinx

写技术文档的人都有一个共同需求：写好一份源码，能自动生成多种格式的文档。不用为每个输出格式单独维护一份文件，这是 Sphinx 解决的核心问题。

它内置了自动索引、代码高亮、交叉引用、层级结构管理。你定义好文档树，Sphinx 自动处理页面之间的链接关系，兄弟页、父页、子页，不用手动维护。对大型项目来说，这一套机制省掉了大量人工维护链接的工作。

2、核心功能

输出格式覆盖几乎所有常见场景。HTML 用于网页发布，PDF 用于离线阅读，EPUB 用于电子书设备，man page 用于 Linux 终端。一个源文件，多个输出目标。

代码高亮基于 Pygments，支持 Python、C、C++、JavaScript 等多种语言。语义化的交叉引用可以自动链接到函数、类、术语表，大型文档项目里找信息很方便。

扩展生态是 Sphinx 的一大优势。社区贡献了大量扩展，有的用来做自动函数文档，有的用来集成 Jupyter 笔记本，有的用来做数学公式渲染。需要什么功能，找对应的扩展装上就行。

3、安装

从 Python Package Index 安装，需要 Python 和 pip。

pip install -U sphinx

4、谁在用

Read the Docs 这个知名的文档托管平台，底层就是 Sphinx。Python 官方文档、Django、Flask、NumPy、Pandas，你能数出来的主流 Python 项目，文档几乎都是用 Sphinx 生成的。

如果你写 Python 库，需要给项目配一套文档，Sphinx 是绕不开的选择。它的 quickstart 工具几分钟就能建好一个文档项目，后续只需要专注写 reStructuredText 文件就好。

做技术写作、产品文档、API 文档的人，都值得试试这个工具。

文件就好。

做技术写作、产品文档、API 文档的人，都值得试试这个工具。