文章目录SphinxPython 文档生成的老牌工具1、为什么用 Sphinx2、核心功能3、安装4、谁在用SphinxPython 文档生成的老牌工具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 sphinx4、谁在用Read the Docs 这个知名的文档托管平台底层就是 Sphinx。Python 官方文档、Django、Flask、NumPy、Pandas你能数出来的主流 Python 项目文档几乎都是用 Sphinx 生成的。如果你写 Python 库需要给项目配一套文档Sphinx 是绕不开的选择。它的 quickstart 工具几分钟就能建好一个文档项目后续只需要专注写 reStructuredText 文件就好。做技术写作、产品文档、API 文档的人都值得试试这个工具。文件就好。做技术写作、产品文档、API 文档的人都值得试试这个工具。