Python有個自帶的工具可以生成Python的項目文檔叫pydoc，但是我覺得最好用的還是Python-Sphinx，這里我們就講一下python-Sphinx的使用。
Sphinx可以自動獲取代碼中的(''' ''' 注釋)，自動生成文檔。
先看看最后要成為的效果，先提起你的興趣
安裝Sphinx
pip install Sphinx
寫個我們需要生成文檔的項目-代碼
建一個測試項目code， 下面有兩個Python文件test1.p y和test2.py
(venv) allenwoo@~/renren$ ls
code venv
(venv) allenwoo@~/renren$ ls code/
test1.py test2.py
test1.py代碼：
# -*-coding:utf-8-*-
class Test1():
'''
我是測試類，負責測試
'''
def hello(self):
'''
負責打印Hello， 人人可以學Python
:return:
'''
print("人人可以學Python")
def renren(self):
'''
測試Sphinx自動生成文檔
:return:
'''
print("自動生成文檔")
class Test2():
def test_2(self):
'''
我也不知道寫什么好，反正我們這里是用來寫文檔的
:return:
'''
print("文檔自動生成測試2")
def renren_2(self):
'''
所以我們開發(fā)的時候就應該在這里寫好文檔，然后用Sphinx自動生成
:return:
'''
print("自動生成文檔2")
test2.py代碼：
# -*-coding:utf-8-*-
def init_test():
'''
用于初始化項目測試，不需要任何參數
:return:
'''
print("初始化項目")
def start():
'''
啟動項目入口，
:return:
'''
test(3)
def test(v):
'''
項目運行主要函數，需要傳入一個參數\n
v:<int>
:return:
'''
print(v)
使用Python-Sphinx doc####
1. 選擇配置
除了以下項目外，其他的我都使用了默認值：
(venv) allenwoo@~/renren/doc$ sphinx-quickstart
Welcome to the Sphinx 1.5.5 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Enter the root path for documentation.
> Root path for the documentation [.]: .
> Separate source and build directories (y/n) [n]: y
> Project name: Code Pro
> Author name(s): Allen Woo
> Project version []: 1.0
> Project language [en]: zh_cn
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/n) [n]: y
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: y
> coverage: checks for documentation coverage (y/n) [n]: y
> viewcode: include links to the source code of documented Python objects (y/n) [n]: y
2.配置conf.py
在source/conf.py文件中加入如下代碼， 導入自己的項目路徑
import os
import sys
sys.path.insert(0, os.path.abspath('./../../code'))
3. 生成rst文件
注意:-o 后面跟的是保存rst文件的路徑， 你的index.rst在哪個目錄，那你就指定哪個目錄。然后在后面的是你的項目(代碼)路徑
(venv) allenwoo@~/renren/doc$ sphinx-apidoc -o ./source ../code/
Creating file ./test1.rst.
Creating file ./test2.rst.
Creating file ./modules.rst.
4. 最后執(zhí)行make html,生成html文件
(venv) allenwoo@~/renren/doc$ make html
Running Sphinx v1.5.5
loading translations [zh_cn]... done
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
no targets are out of date.
build succeeded.
Build finished. The HTML pages are in build/html.
OK！
5.現在我們用瀏覽器打開doc/build/html/index.html,如下：
如果你也和我一樣覺得頁面UI很丑，那就繼續(xù)看下一步，我們安裝一個theme(主題)
主頁面
文檔頁面
源碼頁面
安裝Sphinx主題
python sphinx的主體包郵很多，我最喜歡 readthedocs風格的：
這種風格的sphinx主體包叫sphinx_rtd_theme
可以下載安裝，也可以命令安裝。
命令安裝：
pip install sphinx_rtd_theme
下載地址：
https://github.com/rtfd/sphinx_rtd_theme
注意：下載安裝的配置和使用命令安裝的不一樣，具體可以看GIthub上的文檔：
配置：
編輯我們的source/conf.py
導入模塊：
import sphinx_rtd_theme
將 html_theme = "alabaster"改成如下，在加上html_theme_path
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
最后我們再執(zhí)行一次：make html
然后再訪問文檔，發(fā)現里面變的好看了，是不是？
好了，我們自動生成文檔久到這里了
