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
