當(dāng)準(zhǔn)備一個(gè)項(xiàng)目時(shí)，正確合理的布局（目錄結(jié)構(gòu)）是十分重要的。一個(gè)合理的布局意味著想?yún)⑴c開發(fā)者不必花時(shí)間來(lái)尋找某些代碼的位置; 憑直覺(jué)就可以找到文件的位置。因?yàn)槲覀冊(cè)谔幚硪粋€(gè)項(xiàng)目，就意味著可能需要到處移動(dòng)一些東西。
如你所看到那樣，這里有一些頂層文件，一個(gè)docs目錄（建立一個(gè)空目錄，因?yàn)閟phinx會(huì)將生成的文檔放到這里），一個(gè)sandman目錄，以及一個(gè)在sandman目錄下的test目錄。
setuptools 和 setup.py文件
setup.py文件，你可能已經(jīng)在其它包中看到過(guò)，被distuils包用來(lái)安裝Python包的。對(duì)于任何一個(gè)項(xiàng)目，它都是一個(gè)很重要的文件，因?yàn)樗税姹荆蕾囆畔ⅲ琍yPi需要的項(xiàng)目描述，你的名字和聯(lián)系信息，以及其它一些信息。它允許以編程的方式搜索安裝包，提供元數(shù)據(jù)和指令說(shuō)明讓工具如何做。
其他的setup.py參數(shù)
有一些sandman 用不到的啟動(dòng)參數(shù)，在你的包里可能會(huì)用到。舉個(gè)例子，你可能正在分派一些腳本并希望你的用戶能夠從命令行執(zhí)行。在這個(gè)例子中，腳本會(huì)和你其他的代碼一起安裝在正常的site-packages位置。用戶安裝完后，沒(méi)有其他的簡(jiǎn)單方法運(yùn)行它。基于這一點(diǎn)，setup可以帶有一個(gè)的腳本參數(shù)來(lái)指明Python腳本應(yīng)該如何安裝。在包中安裝一個(gè)調(diào)用go_foo.py的腳本，這個(gè)用來(lái)啟動(dòng)的調(diào)用包括下面這行：
scripts = ['go_foo.py'],
確保在腳本中填入相對(duì)路徑，并不僅僅是一個(gè)名稱 (如scripts = [‘scripts/foo_scripts/go_foo.py’]).同樣，你的腳本應(yīng)該以”shebang”行和”python”開始，如下：
它(README)讀起來(lái)很傻的感覺(jué)，但是確是一個(gè)很重要的文件。它可能是你未來(lái)的用戶或者貢獻(xiàn)者首先從它了解你的項(xiàng)目的。花些時(shí)間來(lái)寫一個(gè)清楚明白的說(shuō)明和使用GFM（GitHubFlavoredMarkdown）來(lái)使它更好看。實(shí)際上，如果使用原生的Markdown來(lái)寫文檔不爽，那么可以在Github上使用立即預(yù)覽來(lái)創(chuàng)建或者修改這個(gè)文件
我們還沒(méi)觸及列表中的第二和第三項(xiàng)（ReadTheDocs和TravisCI），你會(huì)在接下來(lái)看到。
安裝
按照你系統(tǒng)平臺(tái)的git-flow安裝指導(dǎo)操作，在這里。
安裝完后，你可以使用下附命令遷移你的已有項(xiàng)目
$ git flow init
Branch細(xì)節(jié)
腳本將詢問(wèn)你一些配置問(wèn)題，git-flow的默認(rèn)建議值可以很好的工作。你可能會(huì)注意到你的默認(rèn)分支被設(shè)置成develop。現(xiàn)在，讓我們后頭描述一下git-flow…嗯，flow，更詳細(xì)一點(diǎn)。這樣做的最簡(jiǎn)單的方法是討論一下不同的分支及模型中的分支類型。
git flow feature finish
這會(huì)把代碼合并進(jìn)develop分支，并且刪除 feature/
Release
一個(gè)release分支是當(dāng)你準(zhǔn)備好進(jìn)行產(chǎn)品發(fā)布的時(shí)候從develop分支創(chuàng)建出來(lái)的。使用以下的命令來(lái)創(chuàng)建：
$ git flow release start
注意，這是發(fā)布版本號(hào)第一次創(chuàng)建。所有完成的，準(zhǔn)備好發(fā)布的分支必須已經(jīng)合并到develop分支上。在release分支創(chuàng)建后，發(fā)布你的代碼。任何小的bug修改需要提交到 release/
$ git flow release finish
這個(gè)命令會(huì)把你的release/
Hotfix
然而hotfix分支可能會(huì)很有用，在現(xiàn)實(shí)世界中很少使用，至少我是這樣認(rèn)為的。hotfix就像master分支下創(chuàng)建的feature分支： 如果你已經(jīng)關(guān)閉了release分支，但是之后又認(rèn)識(shí)到還有一些很重要的東西需要一起發(fā)布，那么就在master分支（由$git flow release finish
$ git flow hotfix start
當(dāng)你完成改變和增加你的版本號(hào)使之獨(dú)一無(wú)二(bump your version number)，然后完成hotfix分支：
$ git flow hotfix finish
這好像一個(gè)release分支（因?yàn)樗举|(zhì)上就是一種release分支），會(huì)在master和develop分支上提交修改。
我猜想它們很少使用的原因是因?yàn)橐呀?jīng)存在一種可以給已發(fā)布的代碼做出修改的機(jī)制：提交到一個(gè)未完成的release分支。當(dāng)然，可能一開始，團(tuán)隊(duì)使用git flow release finish .. 太早了，然后第二天又發(fā)現(xiàn)需要快速修改。隨著時(shí)間的推移，他們就會(huì)為一個(gè)release 分支多留一些時(shí)間，所以，不會(huì)再需要hotfix分支。另一種需要hotfix分支情況就是如果你立即需要在產(chǎn)品中加入新的特性，等不及在develop分支中加入改變。不過(guò)（期望）這些都是小概率事件。
一旦你安裝了virtualenvwrapper，你需要添加一行內(nèi)容到你的.zhsrc文件(對(duì)bash用戶來(lái)說(shuō)是.bashrc文件)：
$ echo 'source /usr/local/bin/virtualenvwrapper.sh' >> ~/.zshrc
這樣在你的shell中增加了一些有用的命令（記得第一次使用時(shí)source一下你的.zshrc文件以使它生效）。雖然你可以使用mkvirtualenv命令直接創(chuàng)建一個(gè)virtualenv，但使用mkproject [OPTIONS] DEST_DIR創(chuàng)建一個(gè)“項(xiàng)目”將更有用。因?yàn)槲覀円呀?jīng)有一個(gè)現(xiàn)有的項(xiàng)目了，所有我們只需為我們的項(xiàng)目創(chuàng)建一個(gè)新的virtualenv，下附命令可以達(dá)到這效果：
將requirements.txt提交到你的git代碼庫(kù)中。此外，你現(xiàn)在可以添加這里的列出的包列表作為install_requirement參數(shù)的值到setup.py文件中的distutils.setup。這樣做我們可以確保當(dāng)上傳包到PyPI后，它可以被pip安裝并自動(dòng)解決依賴關(guān)系。
使用py.test測(cè)試
在Python的自動(dòng)測(cè)試系統(tǒng)里有兩個(gè)主要的Python標(biāo)準(zhǔn)單元測(cè)試包（很有用）的替代品：nose和py.test。兩個(gè)方案都將單元測(cè)試拓展的易于使用且增加額外的功能。說(shuō)真的，哪個(gè)都是很好的選擇。我更喜歡py.test因?yàn)橄率鰩讉€(gè)原因：
支持setuptools/distutils項(xiàng)目
Python的setup.py測(cè)試技能始終其作用
支持常見的斷言（assert）語(yǔ)法 (而不是需要記住所有jUnit風(fēng)格的斷言函數(shù))
更少的樣板
支持多種測(cè)試風(fēng)格
單元測(cè)試
文檔測(cè)試
nose測(cè)試
使用py.test，我們可以使用Ned Batchelder的覆蓋測(cè)試工具。使用pip安裝pytest-cov。如果你之前這樣運(yùn)行你的測(cè)試：
$ py.test
你可以通過(guò)傳遞一些新的標(biāo)識(shí)生成覆蓋率報(bào)告，下面是運(yùn)行sandman的一個(gè)例子：
當(dāng)然不是所有項(xiàng)目都有100%的測(cè)試覆蓋率（事實(shí)上，正如你讀到的，sandman沒(méi)有100%覆蓋），但獲得100%的覆蓋率是一個(gè)有用的練習(xí)。它能夠揭示我之前沒(méi)有留意的缺陷與重構(gòu)機(jī)會(huì)。
因?yàn)椋鳛闇y(cè)試本身，自動(dòng)生成的測(cè)試覆蓋報(bào)可以作為你持續(xù)集成的一部分。如果你選擇這樣做，部署一個(gè)標(biāo)記來(lái)顯示當(dāng)前的測(cè)試覆蓋率會(huì)為你的項(xiàng)目增加透明度（大多數(shù)時(shí)候會(huì)極大的鼓勵(lì)他人貢獻(xiàn)）。
使用Tox進(jìn)行標(biāo)準(zhǔn)化測(cè)試
一個(gè)所有Python項(xiàng)目維護(hù)者都需要面對(duì)的問(wèn)題是兼容性。如果你的目標(biāo)是同時(shí)支持Python 2.x和Python 3.x（如果你目前只支持Python 2.x，應(yīng)該這樣做），實(shí)際中你如何確保你的項(xiàng)目支持你所說(shuō)的所有版本呢？畢竟，當(dāng)你運(yùn)行測(cè)試時(shí)，你只使用特定的版本環(huán)境來(lái)運(yùn)行測(cè)試，它很可能在Python2.7.5中運(yùn)行良好但在Python 2.6和3.3出現(xiàn)問(wèn)題。
幸運(yùn)的是有一個(gè)工具致力于解決這個(gè)問(wèn)題。tox提供了“Python的標(biāo)準(zhǔn)化測(cè)試”，它不僅僅是在多個(gè)版本環(huán)境中運(yùn)行你的測(cè)試。它創(chuàng)造了一個(gè)完整的沙箱環(huán)境，在這個(gè)環(huán)境中你的包和需求被安裝和測(cè)試。如果你做了更改在測(cè)試時(shí)沒(méi)有異常，但意外地影響了安裝，使用Tox你會(huì)發(fā)現(xiàn)這類問(wèn)題。
通過(guò)一個(gè).ini文件配置tox：tox.ini。它是一個(gè)很容易配置的文件，下面是從tox文檔中摘出來(lái)的一個(gè)最小化配置的tox.ini：
這個(gè)配置文件依舊比較簡(jiǎn)單。而結(jié)果呢？
我從輸出列表里截取了一部分）。如果想看我的測(cè)試對(duì)一個(gè)環(huán)境的覆蓋率，只需運(yùn)行：
結(jié)果很可怕啊。
setuptools整合
tox可以和setuptools整合，這樣python的setup.py測(cè)試可以運(yùn)行你的tox測(cè)試。將下面的代碼段放到你的setup.py文件里，這段代碼是直接從tox的文檔里拿來(lái)的：
文檔需要花費(fèi)一點(diǎn)功夫，但是為了你的使用者，這個(gè)付出是值得的。好吧，好的文檔使一個(gè)可用的項(xiàng)目去其糟粕。
Sphinx的autodoc擴(kuò)展讓我們可以使用很多指令，而這些指令可以自動(dòng)的從你文檔中生成文檔。
安裝
確認(rèn)將Sphinx安裝在你的virtualenv內(nèi)，因?yàn)槲臋n在項(xiàng)目里也是按版本來(lái)的。Sphinx不同的版本可能會(huì)產(chǎn)生不同的HTML輸出。通過(guò)將其安裝在你的virtualenv內(nèi)，你可以以受控的方式升級(jí)你的文檔。
我們要保持我們的文檔在docs文件夾，將文檔生成到docs/generated文件夾。在項(xiàng)目的根目錄運(yùn)行以下命令將根據(jù)你的文檔字符自動(dòng)重構(gòu)文本文檔：
$ sphinx-apidoc -F -o docs
這將產(chǎn)生一個(gè)包含多個(gè)文檔文件的docs文件夾。此外，它創(chuàng)建了一個(gè)叫conf.py的文件，它將負(fù)責(zé)你的文檔配置。你還會(huì)發(fā)現(xiàn)一個(gè)Makefile，方便使用一個(gè)命令（生成html）構(gòu)建HTML文檔。
在你最終生成文檔之前，確保你已經(jīng)在本地安裝了相應(yīng)的包（盡管可以使用pip，但python setup.py develop是最簡(jiǎn)單的保持更新的方法），否則sphinx-apidoc無(wú)法找到你的包。
配置:conf.py
conf.py文件創(chuàng)建用來(lái)控制產(chǎn)生的文檔的各個(gè)方面。它自己會(huì)很好生成文檔，所以我只簡(jiǎn)單地觸及兩點(diǎn)。
版本和發(fā)布
首先，確保你的版本和發(fā)布版本號(hào)保持最新。這些數(shù)字會(huì)作為生成的文檔的一部分顯示，所以你不希望它們遠(yuǎn)離了實(shí)際值。
保持你的版本最新的最簡(jiǎn)單方式就是在你的文檔和setup.py文件中都從你的包的__version__屬性讀取。我從Flask的conf.py借用過(guò)來(lái)配置sandman的conf.py：
PyPI
PyPI，Python包索引（以前被稱為“Cheeseshop”）是一個(gè)公開可用的Python包中央數(shù)據(jù)庫(kù)。PyPI是你的項(xiàng)目發(fā)布的地方。一旦你的包（及其相關(guān)的元數(shù)據(jù)）上傳到PyPI，別人通過(guò)pip或easy_instal可以下載并安裝它。這一點(diǎn)得強(qiáng)調(diào)一下：即使你的項(xiàng)目托管在GitHub，直到被上傳到PyPI后你的項(xiàng)目才是有用的。當(dāng)然，有些人可以復(fù)制你的git庫(kù)任何直接手工安裝它，但更多的人想使用pip來(lái)安裝它。
最后的一步
如果你已經(jīng)完成了所有的前面部分中的步驟，你可能急著想把你的包上傳到PyPI，供其他人使用！
先別急著做上述事情，在分發(fā)你的包之前，有一個(gè)叫做cheesecake的有用的工具有助于運(yùn)行最后一步。它分析你的包并指定一個(gè)分類的數(shù)字分?jǐn)?shù)。它衡量你的包在打包、安裝、代碼質(zhì)量以及文檔的數(shù)量和質(zhì)量方面是否容易/正確。
除了作粗略衡量的“準(zhǔn)備”，cheesecake在完整性檢查方面很優(yōu)秀。你會(huì)很快看到你的setup.py文件是否有錯(cuò)或者有沒(méi)有忘記為一個(gè)文件制作文檔。我建議在上傳每個(gè)項(xiàng)目到PyPI之前運(yùn)行一下它，而不僅只是第一個(gè)。
初始化上傳
現(xiàn)在，你已經(jīng)確定了你的代碼不是垃圾和當(dāng)人們安裝它時(shí)不會(huì)崩潰，讓我們把你的包放到PyPI上吧！你將會(huì)通過(guò)setuptools和setup.py腳本交互。如果這是第一次上傳到PyPI，你將首先注冊(cè)它：
$ python setup.py register
注意：如果你還沒(méi)有一個(gè)免費(fèi)的PyPI賬戶，你將需要現(xiàn)在去注冊(cè)一個(gè)，才能注冊(cè)這個(gè)包[@Lesus 注：注冊(cè)之后還需要到郵箱去驗(yàn)證才行]。在你已使用了上面注冊(cè)之后，你就可以創(chuàng)建發(fā)布包和上傳到PyPI了:
$ python setup.py sdist upload
上面這個(gè)命令建立一個(gè)源碼發(fā)布版(sdist)，然后上傳到PyPI.如果你的包不是純粹的Python（也就是說(shuō)，你有二進(jìn)制需要編譯進(jìn)去），你就需要發(fā)布一個(gè)二進(jìn)制版，請(qǐng)看setuptools文檔，了解更多。
發(fā)布及版本號(hào)
PyPI使用發(fā)行版本模型來(lái)確定你軟件包的哪個(gè)版本是默認(rèn)可用的。初次上傳后，為使你軟件包的每次更新后在PyPI可用，你需要指定一個(gè)新版本號(hào)創(chuàng)建一個(gè)發(fā)布。版本號(hào)管理是一個(gè)相當(dāng)復(fù)雜的課題，PEP有專門的內(nèi)容：PEP 440——版本識(shí)別和依賴指定。我建議參照PEP 400指南（明顯地），但如果你選擇使用不同版本的方案，在setup.py中使用的版本比目前PyPI中的版本“高”，這樣PyPI才會(huì)認(rèn)為這是一個(gè)新版本。
我們項(xiàng)目使用的語(yǔ)言是什么
它使用的是語(yǔ)言的哪個(gè)版本
使用什么命令安裝它
使用什么命令運(yùn)行項(xiàng)目的測(cè)試
這些都是很直接的東西。下面是sandman.travis.yml的內(nèi)容：
你還會(huì)收到一封通知你編譯成功的電子郵件。當(dāng)然你也可以設(shè)置只有在出錯(cuò)或錯(cuò)誤被修復(fù)時(shí)才有郵件通知，但編譯輸出結(jié)果相同時(shí)也不會(huì)發(fā)送。這是非常有用的，你在不必被無(wú)用的“編譯通過(guò)！”郵件淹沒(méi)的同時(shí)在發(fā)生改變?nèi)詴?huì)收到警示。
用ReadTheDocs做持續(xù)文檔集成
盡管PyPI有一個(gè)官方文檔站點(diǎn)（pythonhosted.org），但是ReadTheDocs提供了一個(gè)更好的體驗(yàn)。為什么？ReadTheDocs有針對(duì)GitHub非常棒的集成。當(dāng)你注冊(cè)ReadTheDocs的時(shí)候，你就會(huì)看到你的所有GitHub 代碼庫(kù)。選擇合適的代碼庫(kù)，做一些小幅的配置，那么你的文檔就會(huì)在你每次提交到GitHub之后自動(dòng)重新生成。
配置你的項(xiàng)目應(yīng)該是一個(gè)很直觀的事情。只有一些事需要記住，盡管，這里有一個(gè)配置字段的列表，對(duì)應(yīng)的值可能不一定是你直接用得上的：
Repo: https://github.com/github_username/project_name.git
Default Branch:develop
Default Version:latest
Python configuration file: (leave blank)
Usevirtualenv: (checked)
Requirements file:requirements.txt
Documentation Type: Sphinx HTML
聯(lián)系客服
