[TOC]
Sphinx 简介
Sphinx 是一种工具，是一个有趣 python 的第三方库，它允许程序员以纯文本格式编写文档，Spninx 可以轻松生成各种格式的输出，比如 html，pfd，等等。纯文本的文档方便使用版本管理工具进行跟踪。纯文本文档对不同系统之间的协作者也非常有用，纯文本是当前可以采用的最便捷的格式之一，不然 markdown 格式咋那么火呢，不是没有道理的。
程序员最讨厌的两件事：
- 自己写代码文档
- 别人的代码没文档
正经写文档确实麻烦，为啥麻烦呢？因为很长时间程序员写代码和写文档是完全独立分开的，这说起来就是两份工作量，最不能忍受的还是变化带来的负担，代码是可能经常变动的，代码变动之后，含义自然就可能不一样，或者新加了了功能，文档如果还要手动跟进的话，最喜欢偷懒的程序员自然就不愿了。
我们回归本源，程序员这讨厌的两件事说明了什么？
心有余而力不足。心里还是想写文档的，就是太累了。
所以，对此我们有解决方案吗？
有，最核心的就是代码即文档，根据代码来生成文档。
这个 golang 在语言工具包里就整合了 go doc 这样的工具，能够根据代码和代码里的注释生成一个漂亮的文档。
Python 也有自己的方案，解决文档就是 Sphinx ，Python3.x 官方的文档就是用这个生成的。所以，如果你的也是 Python 项目，那么可以生成一个和官方文档同款的文档项目，非常实用和拉风。
Sphinx 怎么用？
先给大家看一张我本地生成文档项目的图，提提兴趣：
使用这个小工具，你就不用专门写文档项目了，只需要写好代码就好，代码即文档。
安装 sphinx 库
安装非常方便，就是一个简单的 Python 三方库，用 pip 安装就行了：
pip install Sphinx
安装完之后呢，应该有四个二进制文件：
sphinx-apidocsphinx-autogensphinx-buildsphinx-quickstart
如果呢，你没有找到这四个二进制文件，那么可以直接去找对应的 python 文件：
build.pymake_mode.pyquickstart.py
简单示例（ Spninx 使用 ）
搞了一个最简单的示例，项目根目录是 ~/qiya/python-tools/ ，下面都是以此目录为基础，下面的是我自己创建的目录，搞了几个简单的目录，common，misc 是项目的代码目录，docs 是我预定的专门放文档的目录。
root@ubuntu:~/qiya/python-tools# tree
.
├── common
│ ├── demo.py
│ └── __init__.py
├── docs
│ └── __init__.py
├── misc
│ └── __init__.py
│ └── tools.py
└── README.md
我先准备好演示用的代码项目：
demo 类文件：
tools 函数文件：
步骤一：Sphinx 创建出基础配置
执行 sphinx-quickstart
使用 sphinx-quickstart 可以直接做初始化，能够完成最简单的配置，生成一些最基础的配置文件。
$ cd docs/
$ sphinx-quickstart
执行完这个命令，需要配置一些操作，信息如下：
sphinx-quickstart 命令执行完成之后，下面全都是自动生成的文件：
root@ubuntu:~/qiya/python-tools/docs# tree
.
├── build
├── __init__.py
├── make.bat
├── Makefile
└── source
├── conf.py
├── index.rst
├── _static
└── _templates
特意说下，最重要的就是两个文件：
source/conf.py：这个是 Sphinx 的配置，包括主题的设置，文档的生成形式，都可以在这里配置；source/index.rst：这个是项目的主页文件，rst 语法，类似于 markdown，都是一种标记类文档语言；
sphinx-quickstart 执行完之后呢，基础的东西是给你准备好了，接下来就是要根据自身的情况来配置。首先要看的就是 conf.py 这个配置文件，我们的目录是：
root@ubuntu:~/qiya/python-tools# tree
.
├── common
│ ├── demo.py
│ └── __init__.py
├── docs
│ ├── build
│ ├── __init__.py
│ ├── make.bat
│ ├── Makefile
│ └── source
│ ├── conf.py
│ ├── index.rst
│ ├── _static
│ └── _templates
├── misc
│ ├── __init__.py
│ └── tools.py
└── README.md
配置 conf.py 文件
所以呢，我们要让 conf.py 找到代码，那么就要添加好路径，在最开头修改，如下：
import sys
from os.path import abspath, dirname
# 为什么是上三层目录呢？ conf.py 这个文件和根目录不就隔着三层目录嘛
sys.path.insert(0, dirname(dirname(dirname(abspath(__file__)))))
这样 Sphinx 就能找到你想要自动生成文档的代码了。下一步，添加 extensions ，说明咱们的文档可以自动生成：
# 指明用 autodoc 的形式生成
extensions = [
'sphinx.ext.autodoc'
]
# 指明用 sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
sphinx_rtd_theme 这个主题不是默认的，这个是一个比较好看的主题，这个可以直接用 pip 安装即可：
$ pip install sphinx_rtd_theme
conf.py 修改的样子如下：
步骤二：配置项目入口 index.rst
这个 index.rst 文件是入口，项目文档怎么生成，生成什么格式，就是这个文件里配置的（这里的配置是要和 conf 对应着来）。
************
Demo
************
common 公共库
=================
.. automodule:: common.demo
:members:
misc 库
=================
.. automodule:: misc.tools
:members:
解释下，这里的 common.demo 和 misc.tools 模块对应了 py 文件。这个怎么才能找到这两个模块，这个就跟你配置 conf.py 里面的 path 配置有关。
步骤三：生成项目文档
执行命令：
$ cd docs/
$ sphinx-build source/ build/
执行这个命令，就会自动去搜索代码，生成文档项目，默认生成的是 html 的文件。
这里顺带提一下，如果你想生成其他格式的项目文档，比如纯文本格式，那么可以执行：
$ cd docs/
$ sphinx-build -b text source/ build/
纯文本格式如下：
步骤四：展示出来
怎么看到效果呢？演示的话，开一个静态服务器就行，给大家演示一个 python 3 一键起一个静态服务器的命令：
$ python3 -m http.server 9000
显示效果：
小小总结
希望大家写好代码，名字易读，注释规范，这样就自然有好的文档了。还有就是，这个 Sphinx 工具其实不仅适用于 Python，其他语言也能适用，大家可以探索。
坚持思考，方向比努力更重要。微信公众号关注我：奇伢云存储
