python Sphinx 生成简洁大方的文档 2020/6/6 13:28

Sphinx 简介

Sphinx 是一种工具，是一个有趣 python 的第三方库，它允许程序员以纯文本格式编写文档，Spninx 可以轻松生成各种格式的输出，比如 html，pfd，等等。纯文本的文档方便使用版本管理工具进行跟踪。纯文本文档对不同系统之间的协作者也非常有用，纯文本是当前可以采用的最便捷的格式之一，不然 markdown 格式咋那么火呢，不是没有道理的。

程序员最讨厌的两件事：

1. 自己写代码文档
2. 别人的代码没文档

正经写文档确实麻烦，为啥麻烦呢？因为很长时间程序员写代码和写文档是完全独立分开的，这说起来就是两份工作量，最不能忍受的还是变化带来的负担，代码是可能经常变动的，代码变动之后，含义自然就可能不一样，或者新加了了功能，文档如果还要手动跟进的话，最喜欢偷懒的程序员自然就不愿了。

我们回归本源，程序员这讨厌的两件事说明了什么？

心有余而力不足。心里还是想写文档的，就是太累了。

所以，对此我们有解决方案吗？

有，最核心的就是代码即文档，根据代码来生成文档。

这个 golang 在语言工具包里就整合了 go doc 这样的工具，能够根据代码和代码里的注释生成一个漂亮的文档。

Python 也有自己的方案，解决文档就是 Sphinx ，Python3.x 官方的文档就是用这个生成的。所以，如果你的也是 Python 项目，那么可以生成一个和官方文档同款的文档项目，非常实用和拉风。

Sphinx 怎么用？

先给大家看一张我本地生成文档项目的图，提提兴趣：

使用这个小工具，你就不用专门写文档项目了，只需要写好代码就好，代码即文档。

安装 sphinx 库

安装非常方便，就是一个简单的 Python 三方库，用 pip 安装就行了：

pip install Sphinx

安装完之后呢，应该有四个二进制文件：

• sphinx-apidoc
• sphinx-autogen
• sphinx-build
• sphinx-quickstart

如果呢，你没有找到这四个二进制文件，那么可以直接去找对应的 python 文件：

• build.py
• make_mode.py
• quickstar