文章目录
Sphinx 简介
Sphinx 是一种工具,是一个有趣 python 的第三方库,它允许程序员以纯文本格式编写文档,Spninx 可以轻松生成各种格式的输出,比如 html,pfd,等等。纯文本的文档方便使用版本管理工具进行跟踪。纯文本文档对不同系统之间的协作者也非常有用,纯文本是当前可以采用的最便捷的格式之一,不然 markdown 格式咋那么火呢,不是没有道理的。
程序员最讨厌的两件事:
- 自己写代码文档
- 别人的代码没文档
正经写文档确实麻烦,为啥麻烦呢?因为很长时间程序员写代码和写文档是完全独立分开的,这说起来就是两份工作量,最不能忍受的还是变化带来的负担,代码是可能经常变动的,代码变动之后,含义自然就可能不一样,或者新加了了功能,文档如果还要手动跟进的话,最喜欢偷懒的程序员自然就不愿了。
我们回归本源,程序员这讨厌的两件事说明了什么?
心有余而力不足。心里还是想写文档的,就是太累了。
所以,对此我们有解决方案吗?
有,最核心的就是代码即文档,根据代码来生成文档。
这个 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