内容摘要：编完程序还要写文档？你还是饶了程序员吧，我不是写了注释嘛，自己看不行吗？能否把注释变成文档呢，格式好看点，最好还能支持查找、分级目录，还要有例子。要这些你需要知道文档自动化工具，这里就Python生态中的文档自动化工具做一点介绍。
1、Sphinx是什么？
Sphinx英文意思就是埃及那个狮身人面像，但在Python生态里面，它是一种基于Python的文档工具，它可以令人轻松的撰写出清晰且优美的文档。借助这个第三方工具，可以提取Python代码中的说明文档，并生成html文件。
在使用python中，我们一般在模块，类，函数下使用docstring添加字符串说明性文档，使开发人员更好的可以看懂此代码是做什么用的。然而写了那么多的注释，我们想要一篇文档怎么办，第一种办法不可能将写完的注释直接手动的ctrl+c ctrl+v的，此时sphinx就出现了，解决了这一问题。
啥不知道什么是“Docstring”，docstring说白了就是一堆代码中的注释。任何编程语言都有注释，但是，Python的docstring可以通过help函数直接输出一份有格式的文档，这个就厉害了。代码写完，注释写完，一个help调用，就有文档看了。
2、怎么安装，怎么使用
这么好用，我要马上安装，安装方式如下：
pip install sphinx
对就这一行就够了。啥太简单，还能复杂点不？那看下边的：
pip install sphinx sphinx-autobuild sphinx_rtd_theme recommonmark
这个命令实现了一些主题等应用，多记住点没坏处。接下来我们来生成文档吧！
第一步：建立一个工程目录
mkdir project
cd project
sphinx-quickstart
运行sphinx-quickstart命令后，会出现一些交互式信息填写，直接填就好了，一次不行下次修改本地配置也可以改。
运行结束会在project目录下，产生一些文件和目录，这些内容就是后面生成html的关键。
第二步：修改conf.py配置
找到project目录下source/conf.py文件，记事本打开。
由于默认网站比较原始，建议修改网页主题，一般Python项目都会用经典的sphinx_rtd_theme主题，修改conf.py文件，找到html_theme的代码，然后按下面代码修改即可。
# html_theme = 'alabaster'
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
如果期望sphinx文档支持Markdown源文件，在前面的配置文件中找到source_suffix，修改成下面的配置即可。
# source_suffix = '.rst'
from recommonmark.parser import CommonMarkParser
source_parsers = {
'.md': CommonMarkParser,
}
source_suffix = ['.rst', '.md']
第三步：从代码生成rst文件
运行（注意错误提示，有问题的要即使修改，warning可以不用管）：
sphinx-apidoc -o outputdir packagedir
其中：outputdir是source的目录，packagedir是代码所在的目录
第四步：生成静态html文件
运行：
make html
成后后，会在本地生成build/html/index.html等文件，在浏览器中打开就可以看到下面的页面了，也就是说把本地的文档源文件(.md .rst等)渲染成一个网站。
结语：
Sphinx生成的HTML渲染页面，是存静态的，在本地直接可以使用浏览器打开。当然这些文档代码也可以在Github中托管，通过pages服务，自己不需要服务器就可以构建一套文档服务了。readthedocs.org这个网站就提供此类服务，程序员要做的就是提交代码到GitHub，剩下的更新全部交给自动化配置完成。是不是很简单？！
