sphinx自动化文档
sphinx是python的御用自动化文档模块，通过提取代码中的文档注释（docstring）来生成代码文档，还是很方便的，你看到很多python官方教程，其实都是sphinx生成的，比如数据分析的pandas:http://pandas.pydata.org/pandas-docs/stable/
废话不多说，下面开始。
需要注意的是，我使用的python3.5，sphinx1.4.
安装sphinx和sphinx_bootstrap_theme主题
安装方法可以使用pip方法安装，也可以先将源码包下载后使用setup安装。个人觉得sphinx_bootstrap_theme比sphinx中包含的几个主题要好看一些。
sphinx的官网地址:http://www.sphinx-doc.org/en/1.4.8/
sphinx_bootstrap_theme主题地址:http://ryan-roemer.github.io/sphinx-bootstrap-theme/
建立sphinx项目
在代码目录下安装shift+鼠标右键，打开cmd窗口，我的目录地址是 E:\pycharm
然后依次输入如下命令，注意，如果没有输入直接回车，则是使用默认选型
E:\pycharm> sphinx-quickstart
> Root path for the documentation [.]: doc # 在当前目录下新建doc文件夹存放sphinx相关信息
> Separate source and build directories (y/n) [n]: # 默认，直接回车
> Name prefix for templates and static dir [_]:
> Project name: python123 # 输入项目名称
> Author name(s): 123 # 作者
> Project version: 1.0 # 项目版本
> Project release [1.0]:
> Project language [en]: # 默认，回车
> Source file suffix [.rst]:
> Name of your master document (without suffix) [index]:
> Do you want to use the epub builder (y/n) [n]:
> autodoc: automatically insert docstrings from modules (y/n) [n]: y # 这个很重要，输入y
> doctest: automatically test code snippets in doctest blocks (y/n) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]:
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]:
> coverage: checks for documentation coverage (y/n) [n]:
> pngmath: include math, rendered as PNG images (y/n) [n]:
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]:
> ifconfig: conditional inclusion of content based on config values (y/n) [n]:
> viewcode: include links to the source code of documented Python objects (y/n) [n]: y # 很重要，输入y，表示将源码也放到文档中，你看很多python的模块的文档，其实都是包含代码的。
> Create Makefile? (y/n) [y]:
> Create Windows command file? (y/n) [y]:
# 之后会在doc目录下生成如下文件
E:.
│ conf.py
│ index.rst
│ make.bat
│ Makefile
│
├─_build
├─_static
└─_templates生成apidoc
还是在刚才的目录下 E:\pycharm 打开cmd
# 对当前目录的每一个文件夹及子文件夹生成一个rst文件，对应python的包，存放在./doc目录下
sphinx-apidoc -o ./doc/ .
# 之后会在doc文件夹下看到很多刚才生成的rst文件
E:.
│ ahp_model_ys.rst
│ conf.py
│ config.rst
│ control_all_data_and_process.rst
│ data_etl.rst
│ dynamic_proc.rst
│ ex_data.oracle_imp_exp.rst
│ ex_data.rst
│ index.rst
│ keywords.rst
│ log_ys.rst
│ make.bat
│ Makefile
│ modules.rst
│ predict_by_rule_ys.rst
│ similar_prison_ys.rst
│ tools_py.backup_ys.rst
│ tools_py.cmd_py.rst
│ tools_py.database.rst
│ tools_py.email_ys.rst
│ tools_py.linux.rst
│ tools_py.rst
│ tools_py.sched_py.rst
│ tools_py.time_py.rst
│ trace_sql_info.rst
修改conf
进入doc目录，修改conf.py文件。
# 1.增加搜索目录
# 找到 #sys.path.insert(0, os.path.abspath('.'))，去掉注释并修改为
sys.path.insert(0, os.path.abspath('..'))
# 2.修改主题
# 在文件的开头导入刚才安装的主题
import sphinx_bootstrap_theme
# 找到html_theme，修改为
html_theme = 'bootstrap'
# 找到html_theme_path，修改为
html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
# 找到html_theme_options，修改为
html_theme_options = {
'navbar_title': "你的项目名称",
'globaltoc_depth': 2,
'globaltoc_includehidden': "true",
'navbar_class': "navbar navbar-inverse",
'navbar_fixed_top': "true",
'bootswatch_theme': "united",
'bootstrap_version': "3",
}sphinx_bootstrap_theme的参数调节请参考其官方文档。
修改index.rst
打开doc目录下的index.rst文件，你可以在这里写上一起其他的欢迎信息，简要说明，或者注意事项。需要注意的是，sphinx的语法和markdown差不多，使用空行表示换行。
在 :maxdepth: 2 下面增加modules.rst，表示目录
最后的我修改的样子如下，注意要去掉括号里面的注释。
.. python123 documentation master file, created by
sphinx-quickstart on Tue Oct 25 14:30:26 2016.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
你好啊，这是一级标题
================== （注意，可以用=或者-表示标题，只要长度大于标题就可以了）
空一行，这里写些其他内容，简介或者注意事项。
当然你也可以加入代码，后面加两个冒号，然后缩进 ::
import pandas as pd
pd.DataFrame()
更多格式，可以参考：
http://blog.csdn.net/jianhong1990/article/details/8256598
Contents:
.. toctree::
:maxdepth: 2 （目录树深度，不要展开太多）
modules.rst （这里空一行加入目录，当然也可以加其他rst。注意要和上面的平级，）
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
修改modules.rst
# 将modules.rst第一行的点号修改为 '显示目录'，当然可以不改。
# 第一行的等号多写几个，长度大于第一行
# 树深度改为3
显示目录
=========
.. toctree::
:maxdepth: 3编译
在doc目录下打开cmd，执行 make html，过一会就可以在 doc\_build\html目录下看到编译生成的网页文件了。
严重的排版问题
由于sphinx使用空行表示换行，这就会导致，如果想要在网页端可到好看的结果，那么代码文件中的注释就需要很多空行，如果想在代码文件中把注释写得好看点，那么网页端排版可能就不好看了。
另一个问题是缩进问题，一个大问题总会分解成几个小问题吧，或者一个问题有几个小步骤，这时候分几点然后缩进排版是很正常的。
比如下面的源码中的注释：
为了保持网页端的排版好看，我可能需要这样写注释。
上面空了一行，否则你在源码中看到的换行，在网页端其实并没有换行。
又比如缩进问题：
又要空一行，真的是浪费啊，而且也不是那么好看了。如果这里缩进，就会变成列表了，其实在网页端是不好看的。
不信你试试但是在正常的情况下，你肯定不会写这么多空行吧，真实的情况只有在两个段落差异比较大的情况才会这样换行吧，下面是更多见的注释情况吧
为了保持网页端的排版好看，我可能需要这样写注释。
一般情况下谁没事会经常空一行表示换行呢？直接回车就行了嘛，代码已经不好看了，注释还不能好看。
(下面空一行，表示两个段落的分割)
又比如缩进问题：
我这里不想空一行再缩进，想要直接缩进，就像这样子。
可是它会变成列表那样子，排版上其实是不好看的。
不信你试试那么有没有办法既能兼顾代码注释的美观，又能使生成的网页比较好看呢？
答案是不能的，只能曲线处理，就是牺牲代码注释一点点的美观，换取不要写那么多空行。
使用特殊的换行标记
比如在注释中，每一行的末尾都加入<p>，这样生成网页后，将所有网页的这个<p>标记替换成</p><p>实现换行。
虽然不是高明，但是也还过得去。
缩进问题，比如在行首加上.号防止被识别为列表缩进，然后空4个空格接着写注释，对生成的网页文件，将这个（点号+4个空格）替换成网页能识别的空格 即可。
那么代码注释就会变成这样了：
为了保持网页端的排版好看，我可能需要这样写注释。 <p>
在每一行的后面都加一个 <p>，这样就可以后期直接修改网页源码使之变成换行符<p>
(下面空一行，表示两个段落的分割)
又比如缩进问题： <p>
. 我在前面加上点号，然后几个空格，后期可以直接对网页源码修改为几个空格即可实现缩进。<p>
. 不信你试试<p>使用块缩进
上面的方法虽然可行，但是步骤还是多了写，而且需要在生成网页后批量修改网页源代码。
有一个比较笨，但是也还不错的方法，就是所用块缩进，也就是在每一行起始用|（竖线+空格）表示块，这样就间接解决了换行问题，唯一不足的地方是，没有那么好看了。
修改后的注释是这样的：
| 为了保持网页端的排版好看，我可能需要这样写注释。
| 在每一行的前面都加上竖线和空格，这样每一行都是一块，不需要使用空行换行
| 而且也不是那么难看，勉强可以接受
| (下面空一行，表示两个段落的分割)
|
| 又比如缩进问题：
| 这里想缩进多少就缩进多少，最终网页就是你所看到的这个样子
| 不信你试试
|
| 此时不同的缩进层次就明朗了当然，如果是函数的注释，而且注释也不长，就没必要搞这么麻烦了，使用空行可能会方便一些。
看情况吧。
参考
http://www.sphinx-doc.org/en/1.4.8/
http://sphinx-bootstrap-theme.readthedocs.io/en/latest/
http://blog.csdn.net/weishantc/article/details/46729103
http://blog.csdn.net/handsomekang/article/details/46830083
http://blog.csdn.net/jianhong1990/article/details/8256598
http://pm.readthedocs.io/doc/sphinx.html
