內(nèi)容摘要：編完程序還要寫(xiě)文檔最爬？你還是饒了程序員吧，我不是寫(xiě)了注釋嘛门岔，自己看不行嗎烂叔？能否把注釋變成文檔呢，格式好看點(diǎn)固歪，最好還能支持查找蒜鸡、分級(jí)目錄，還要有例子牢裳。要這些你需要知道文檔自動(dòng)化工具逢防，這里就Python生態(tài)中的文檔自動(dòng)化工具做一點(diǎn)介紹。
1蒲讯、Sphinx是什么忘朝？
Sphinx英文意思就是埃及那個(gè)獅身人面像，但在Python生態(tài)里面判帮，它是一種基于Python的文檔工具局嘁，它可以令人輕松的撰寫(xiě)出清晰且優(yōu)美的文檔。借助這個(gè)第三方工具晦墙，可以提取Python代碼中的說(shuō)明文檔悦昵，并生成html文件。
在使用python中晌畅，我們一般在模塊但指，類(lèi)，函數(shù)下使用docstring添加字符串說(shuō)明性文檔抗楔，使開(kāi)發(fā)人員更好的可以看懂此代碼是做什么用的棋凳。然而寫(xiě)了那么多的注釋?zhuān)覀兿胍黄臋n怎么辦，第一種辦法不可能將寫(xiě)完的注釋直接手動(dòng)的ctrl+c ctrl+v的连躏，此時(shí)sphinx就出現(xiàn)了剩岳，解決了這一問(wèn)題。
啥不知道什么是“Docstring”入热，docstring說(shuō)白了就是一堆代碼中的注釋拍棕。任何編程語(yǔ)言都有注釋?zhuān)瞧Ｓ兀琍ython的docstring可以通過(guò)help函數(shù)直接輸出一份有格式的文檔，這個(gè)就厲害了莫湘。代碼寫(xiě)完尤蒿，注釋寫(xiě)完，一個(gè)help調(diào)用幅垮，就有文檔看了腰池。
2、怎么安裝忙芒，怎么使用
這么好用示弓，我要馬上安裝，安裝方式如下：
pip install sphinx
對(duì)就這一行就夠了呵萨。啥太簡(jiǎn)單奏属，還能復(fù)雜點(diǎn)不？那看下邊的：
pip install sphinx sphinx-autobuild sphinx_rtd_theme recommonmark
這個(gè)命令實(shí)現(xiàn)了一些主題等應(yīng)用潮峦，多記住點(diǎn)沒(méi)壞處囱皿。接下來(lái)我們來(lái)生成文檔吧！
第一步：建立一個(gè)工程目錄
mkdir project
cd project
sphinx-quickstart
運(yùn)行sphinx-quickstart命令后忱嘹，會(huì)出現(xiàn)一些交互式信息填寫(xiě)嘱腥，直接填就好了，一次不行下次修改本地配置也可以改拘悦。
運(yùn)行結(jié)束會(huì)在project目錄下齿兔，產(chǎn)生一些文件和目錄，這些內(nèi)容就是后面生成html的關(guān)鍵础米。
第二步：修改conf.py配置
找到project目錄下source/conf.py文件分苇，記事本打開(kāi)。
由于默認(rèn)網(wǎng)站比較原始屁桑，建議修改網(wǎng)頁(yè)主題医寿，一般Python項(xiàng)目都會(huì)用經(jīng)典的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文件
運(yùn)行（注意錯(cuò)誤提示准浴，有問(wèn)題的要即使修改，warning可以不用管）：
sphinx-apidoc -o outputdir packagedir
其中：outputdir是source的目錄捎稚，packagedir是代碼所在的目錄
第四步：生成靜態(tài)html文件
運(yùn)行：
make html
成后后乐横，會(huì)在本地生成build/html/index.html等文件求橄，在瀏覽器中打開(kāi)就可以看到下面的頁(yè)面了，也就是說(shuō)把本地的文檔源文件(.md .rst等)渲染成一個(gè)網(wǎng)站葡公。
結(jié)語(yǔ)：
Sphinx生成的HTML渲染頁(yè)面罐农，是存靜態(tài)的，在本地直接可以使用瀏覽器打開(kāi)催什。當(dāng)然這些文檔代碼也可以在Github中托管涵亏，通過(guò)pages服務(wù)，自己不需要服務(wù)器就可以構(gòu)建一套文檔服務(wù)了蒲凶。readthedocs.org這個(gè)網(wǎng)站就提供此類(lèi)服務(wù)气筋，程序員要做的就是提交代碼到GitHub，剩下的更新全部交給自動(dòng)化配置完成旋圆。是不是很簡(jiǎn)單宠默？！
