|
浪小九 2018-08-15 12:29:07 前言 大多數(shù)Python開發(fā)者至少都寫過一個(gè)像工具、腳本、庫或框架等對(duì)其他人也有用的工具。我寫這篇文章的目的是讓現(xiàn)有Python代碼的開源過程盡可能清晰和無痛。我不是簡單的指——“創(chuàng)建一個(gè)GitHub庫，提交，在Reddit上發(fā)布，每天調(diào)用它”。在本文的結(jié)尾，你可以把現(xiàn)有的代碼轉(zhuǎn)換成一個(gè)能夠鼓勵(lì)他人使用和貢獻(xiàn)的開源項(xiàng)目。 喜歡的話就轉(zhuǎn)發(fā)在下方評(píng)論留下你的見解哦！ 然而每一個(gè)項(xiàng)目都是不同的，但其中將現(xiàn)有代碼開源的流程對(duì)所有的Python項(xiàng)目都是類似的。在另一個(gè)受歡迎的文章系列里我寫了“以正確方式開始一個(gè)Django項(xiàng)目”，我將概述在開源Python項(xiàng)目我發(fā)現(xiàn)的有必要的步驟。 工具和概念 特別是，我發(fā)現(xiàn)一些工具和概念十分有用或者說是必要的。下面我就會(huì)談及這方面主題，包括需要運(yùn)行的精確的命令和需要設(shè)置的配置值。其終極目標(biāo)就是讓整個(gè)流程簡單明了。
項(xiàng)目布局 當(dāng)準(zhǔn)備一個(gè)項(xiàng)目時(shí)，正確合理的布局（目錄結(jié)構(gòu)）是十分重要的。一個(gè)合理的布局意味著想?yún)⑴c開發(fā)者不必花時(shí)間來尋找某些代碼的位置; 憑直覺就可以找到文件的位置。因?yàn)槲覀冊(cè)谔幚硪粋€(gè)項(xiàng)目，就意味著可能需要到處移動(dòng)一些東西。 讓我們從頂層開始。大多數(shù)項(xiàng)目都有很多頂層文件（如setup.py, README.md, requirements等等）。每個(gè)項(xiàng)目至少應(yīng)該有下面三個(gè)目錄：
為了更好理解文件該如何組織，這里是一個(gè)我的簡單項(xiàng)目：sandman 布局快照。  如你所看到那樣，這里有一些頂層文件，一個(gè)docs目錄（建立一個(gè)空目錄，因?yàn)閟phinx會(huì)將生成的文檔放到這里），一個(gè)sandman目錄，以及一個(gè)在sandman目錄下的test目錄。 setuptools 和 setup.py文件 setup.py文件，你可能已經(jīng)在其他包中看到過，被distuils包用來安裝Python包的。對(duì)于任何一個(gè)項(xiàng)目，它都是一個(gè)很重要的文件，因?yàn)樗税姹?，包依賴信息，PyPi需要的項(xiàng)目描述，你的名字和聯(lián)系信息，以及其它一些信息。它允許以編程的方式搜索安裝包，提供元數(shù)據(jù)和指令說明讓工具如何做。 setuptools包（實(shí)際上就是對(duì)distutils的增強(qiáng)）簡單化了建立發(fā)布python包。使用setuptools給python包打包，和distutils打包沒什么區(qū)別。這實(shí)在是沒有任何理由不使用它。 setup.py應(yīng)該放在你的項(xiàng)目的根目錄。setup.py中最重要的一部分就是調(diào)用setuptools.setup，這里面包含了此包所需的所有元信息。這里就是sandman的setup.py的所有內(nèi)容  （感謝Christian Heimes的建議讓setup.py更符合人們的語言習(xí)慣。反過來，也讓我借用其他的項(xiàng)目一目了然了。) 大多數(shù)內(nèi)容淺顯易懂，可以從setuptools文檔查看到，所以我只會(huì)觸及"有趣"的部分。使用sandman.__version__和gettinglong_description方法（盡管我也記不住是哪一個(gè)，但是卻可以從其它項(xiàng)目的setup.py中獲得）來減少我們需要寫的引用代碼。相反，維護(hù)項(xiàng)目的版本有三個(gè)地方(setup.py, 包自身的__version__， 以及文檔)，我們也可以使用包的version來填充setup里面的version參數(shù) long_description被Pypi在你項(xiàng)目的PyPI主頁當(dāng)做文檔使用。這里有其他一個(gè)文件，README.md，其中包含幾乎相同的內(nèi)容，我使用pandoc依據(jù)README.md自動(dòng)生成README.rst，因此我們只需看README.rst就行了，并將它的內(nèi)容設(shè)置為long_description。 py.test (上面討論過) 中有一個(gè)特殊的條目（pytest類）設(shè)置允許Python檢查setup.py可否正常工作。這段代碼直接來自py.test指導(dǎo)文檔。 文件中的其他內(nèi)容都是在設(shè)置文檔中描述的安裝參數(shù)。 其他的setup.py參數(shù) 有一些sandman 用不到的啟動(dòng)參數(shù)，在你的包里可能會(huì)用到。舉個(gè)例子，你可能正在分派一些腳本并希望你的用戶能夠從命令行執(zhí)行。在這個(gè)例子中，腳本會(huì)和你其他的代碼一起安裝在正常的site-packages位置。用戶安裝完后，沒有其他的簡單方法運(yùn)行它?；谶@一點(diǎn)，setup可以帶有一個(gè)的腳本參數(shù)來指明Python腳本應(yīng)該如何安裝。在包中安裝一個(gè)調(diào)用go_foo.py的腳本，這個(gè)用來啟動(dòng)的調(diào)用包括下面這行：  確保在腳本中填入相對(duì)路徑，并不僅僅是一個(gè)名稱 (如scripts = [''scripts/foo_scripts/go_foo.py'']).同樣，你的腳本應(yīng)該以"shebang"行和"python"開始，如下：  distutils將會(huì)在安裝過程中自動(dòng)用當(dāng)前解釋器位置取代這一行。 如果你的包比我們這里討論的要復(fù)雜，你可在官方文檔中參看啟動(dòng)工具文檔和分布python模塊。 在這兩者中，你可以解決一些你可能會(huì)遇到的問題。 代碼管理：git， 項(xiàng)目管理：gitHub 在“以正確的方式開始一個(gè)Django項(xiàng)目”中，我建議版本控制使用git 或者 mercurial。如果對(duì)于以共享與貢獻(xiàn)的項(xiàng)目來說，只有一個(gè)選擇：git。事實(shí)上，從長遠(yuǎn)來說，如果你想人們能使用和參與貢獻(xiàn)，那么不僅使用git很有必要，而且，你也能夠使用GitHub來管理維護(hù)你的項(xiàng)目。 這并不是夸大其詞（盡管很多人會(huì)以它為嚼頭）。然而，管它好與差，git和GitHub事實(shí)上已經(jīng)成為了開源項(xiàng)目的實(shí)際標(biāo)準(zhǔn)了。GitHub是很多潛在的貢獻(xiàn)者最想注冊(cè)的和最熟悉的。所以，我深信，這并不是掉以輕心，而是深思熟慮的產(chǎn)物。 新建一個(gè)README.md文件 在GitHub的代碼倉庫中，項(xiàng)目的描述是從項(xiàng)目的根目錄中的:README.md文件獲取的。這個(gè)文件應(yīng)該包含下面幾點(diǎn)：
它(README)讀起來很傻的感覺，但是確是一個(gè)很重要的文件。它可能是你未來的用戶或者貢獻(xiàn)者首先從它了解你的項(xiàng)目的?；ㄐr(shí)間來寫一個(gè)清楚明白的說明和使用GFM（GitHubFlavoredMarkdown）來使它更好看。實(shí)際上，如果使用原生的Markdown來寫文檔不爽，那么可以在Github上使用立即預(yù)覽來創(chuàng)建或者修改這個(gè)文件 我們還沒觸及列表中的第二和第三項(xiàng)（ReadTheDocs和TravisCI），你會(huì)在接下來看到。 使用"Issues"頁 跟生活中的很多事情一樣，你投入GitHub越多，你收獲的越多。因?yàn)橛脩魰?huì)使用GitHub的“Issues”頁面反饋bug，使用該頁面跟蹤特性要求和改進(jìn)是很有意義的。 更重要的是，它允許貢獻(xiàn)者以一種優(yōu)雅的方式看到：一個(gè)可能實(shí)現(xiàn)特性的列表以及自動(dòng)化的管理合并請(qǐng)求流程（pull request）。GitHub的issues可以與評(píng)論、你項(xiàng)目里的其他issues及其他項(xiàng)目里的issues等交織，這使得“issues”頁面成為一個(gè)有關(guān)所有bug修復(fù)、改進(jìn)和新特性要求信息匯總的地方。 確保“Issues”及時(shí)更新，至少及時(shí)回應(yīng)新的問題。作為一個(gè)貢獻(xiàn)者，沒有什么比修復(fù)bug后看著它呈現(xiàn)在issues頁面并等待著被合并更有吸引力的了。 使用git-flow這個(gè)明智的git工作流 為使事情對(duì)自己和貢獻(xiàn)者更容易，我建議使用非常流行的git-flow分支模型。 概述 開發(fā)分支是你工作的主要分支，它也是將成為下一個(gè)release.feature的分支，代表著即將實(shí)現(xiàn)的新特性和尚未部署的修復(fù)內(nèi)容（一個(gè)完整的功能分支有開發(fā)分支合并而來）。通過release的創(chuàng)建更新master。 安裝 按照你系統(tǒng)平臺(tái)的git-flow安裝指導(dǎo)操作，在這里。 安裝完后，你可以使用下附命令遷移你的已有項(xiàng)目  Branch細(xì)節(jié) 腳本將詢問你一些配置問題，git-flow的默認(rèn)建議值可以很好的工作。你可能會(huì)注意到你的默認(rèn)分支被設(shè)置成develop。現(xiàn)在，讓我們后頭描述一下git-flow…嗯，flow，更詳細(xì)一點(diǎn)。這樣做的最簡單的方法是討論一下不同的分支及模型中的分支類型。 Master master分支一直是存放“生產(chǎn)就緒”的代碼。所有的提交都不應(yīng)該提交到master分支上。當(dāng)然，master分支上的代碼只會(huì)從一個(gè)產(chǎn)品發(fā)布分支創(chuàng)建并結(jié)束后合并進(jìn)來。這樣在master上的代碼一直是可以發(fā)布為產(chǎn)品的。并且，master也是一直處于可預(yù)計(jì)的狀態(tài)，所以你永遠(yuǎn)不需要擔(dān)心如果master分支修改了而某一個(gè)其他分支沒有相應(yīng)的修改。 Develop 你的大部分工作是在develop分支上完成的。這個(gè)分支包含所有的完成的特性和修改的bug以便發(fā)布；每日構(gòu)建或者持續(xù)集成服務(wù)器需要針對(duì)develop分支來進(jìn)行，因?yàn)樗碇鴮?huì)被包含在下一個(gè)發(fā)布里的代碼。 對(duì)于一次性的提交，可以隨便提交到develop上。 特性 對(duì)于一些大的特性，就需要?jiǎng)?chuàng)建一個(gè)特性分支。特性分支從develop分支創(chuàng)建出來。它們可以是對(duì)于下一個(gè)發(fā)布的一些小小的增強(qiáng)或者更進(jìn)一步的修改。而這，依然需要從現(xiàn)在開始工作。為了從一個(gè)新的分支上開始工作，使用：  這命令創(chuàng)建了一個(gè)新的分支：feature/<feature name>。通常會(huì)把代碼提交到這個(gè)分支。當(dāng)特性已經(jīng)完成并且準(zhǔn)備好發(fā)布的時(shí)候，它就應(yīng)當(dāng)用一下的命令將它合并會(huì)develop分支：  這會(huì)把代碼合并進(jìn)develop分支，并且刪除 feature/<feature name>分支 Release 一個(gè)release分支是當(dāng)你準(zhǔn)備好進(jìn)行產(chǎn)品發(fā)布的時(shí)候從develop分支創(chuàng)建出來的。使用以下的命令來創(chuàng)建：  注意，這是發(fā)布版本號(hào)第一次創(chuàng)建。所有完成的，準(zhǔn)備好發(fā)布的分支必須已經(jīng)合并到develop分支上。在release分支創(chuàng)建后，發(fā)布你的代碼。任何小的bug修改需要提交到 release/<release number>分支上。當(dāng)所有的bug被修復(fù)之后，運(yùn)行以下的命令：  這個(gè)命令會(huì)把你的release/<release number> 分支合并到master和develop分支，這意味著你永遠(yuǎn)不需要擔(dān)心這幾個(gè)分支會(huì)缺少一些必要的產(chǎn)品變更（可能是因?yàn)橐粋€(gè)快速的bug修復(fù)導(dǎo)致的）。 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 <release number>創(chuàng)建的標(biāo)簽）下創(chuàng)建一個(gè)hotfix分支，就像這樣：  當(dāng)你完成改變和增加你的版本號(hào)使之獨(dú)一無二(bump your version number)，然后完成hotfix分支：  這好像一個(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分支中加入改變。不過（期望）這些都是小概率事件。 virtualenv和virtualenvwrapper lan Bicking的virtualenv工具事實(shí)上已經(jīng)成為了隔離Python環(huán)境的標(biāo)準(zhǔn)途徑了。它的目標(biāo)很簡單：如果你的一臺(tái)機(jī)子中有很多Python項(xiàng)目，每個(gè)都有不同的依賴（可能相同的包，但是依賴不同的版本），僅僅在一個(gè)Python安裝環(huán)境中管理這些依賴幾乎是不可能的。 virtualenv創(chuàng)建了一個(gè)“虛擬的”Python安裝環(huán)境，每個(gè)環(huán)境都是相互隔離的，都有自己的site-packages, distribute和 使用pip安裝包到虛擬環(huán)境而不是系統(tǒng)Python安裝環(huán)境。 而且在你的虛擬環(huán)境中來回切換只是一個(gè)命令的事。 Doug Hellmann的virtualenvwrapper使創(chuàng)建和管理多個(gè)虛擬環(huán)境更容易的隔離工具。讓我們繼續(xù)前進(jìn)，馬上安裝這兩個(gè)工具： 如你所見，后者依賴于前者，所以簡單的安裝virtualenvwrapper就足夠了。注意，如果你使用的是Python3，PEP-405通過venv包和pyvenv命令提供了Python原生虛擬環(huán)境的支持，在python3.3中已實(shí)現(xiàn)。你應(yīng)該使用這個(gè)而不是前面提到的工具。 一旦你安裝了virtualenvwrapper，你需要添加一行內(nèi)容到你的.zhsrc文件(對(duì)bash用戶來說是.bashrc文件)： 這樣在你的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á)到這效果： 你會(huì)注意到你的shell提示符在你的virtualenv之后（我的是“ossproject”，你可以使用任何你喜歡的名字）?，F(xiàn)在任何通過pip安裝的模塊將安裝到你的virtualenv下的site-packages。 要停止在你的項(xiàng)目上工作并切換回系統(tǒng)使用deactivate命令。你會(huì)看到命令提示符前你的virtualenv名字消失了。要重新回到你的項(xiàng)目上工作的話運(yùn)行workon <project name>，你會(huì)回到你的virtualenv。 除了簡單地為你的項(xiàng)目創(chuàng)建virtualenv，你還會(huì)用它做其他事：生成你的requirements.txt文件，使用requirements.txt文件和-r標(biāo)識(shí)可安裝所有項(xiàng)目的依賴項(xiàng)。要?jiǎng)?chuàng)建該文件，在你的virtualenv運(yùn)行以下命令（一旦你代碼和virtualenv一起工作，就是那里）： 你會(huì)得到一個(gè)所有你項(xiàng)目需要模塊的列表，它以后可以被setup.py文件使用列出你的依賴關(guān)系。這里有一點(diǎn)需要注意：我經(jīng)常在requirements.txt中將“==”改為“>=“，這樣代表“我正使用包的任何的后來版本”。你是否應(yīng)該或需要在項(xiàng)目這樣做取決于實(shí)際情況，但我應(yīng)該指出來。 將requirements.txt提交到你的git代碼庫中。此外，你現(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è)試拓展的易于使用且增加額外的功能。說真的，哪個(gè)都是很好的選擇。我更喜歡py.test因?yàn)橄率鰩讉€(gè)原因：
注意 如果你已經(jīng)有了一個(gè)自動(dòng)測(cè)試的解決方案那繼續(xù)使用它吧，跳過這一節(jié)。但請(qǐng)記住以后的章節(jié)你將被認(rèn)為在使用py.test測(cè)試，這可能會(huì)影響到配置值。 測(cè)試安裝 在測(cè)試目錄里，無論你如何決定都要有這個(gè)目錄，創(chuàng)建一個(gè)名為test_<project_name>.py的文件。py.test的測(cè)試發(fā)現(xiàn)機(jī)制將把所有test_前綴的文件當(dāng)做測(cè)試文件處理（除非明確告知）。 在這個(gè)文件里放什么很大程度上取決于你。寫測(cè)試是一個(gè)很大的話題，超出這篇文章的范圍。最重要的，測(cè)試對(duì)你的和潛在的捐助者都是有用的。應(yīng)該標(biāo)識(shí)清楚每個(gè)用例是測(cè)試的什么函數(shù)。用例應(yīng)該以相同的“風(fēng)格”書寫，這樣潛在的貢獻(xiàn)者不必猜測(cè)在你的項(xiàng)目中他/她應(yīng)該使用三種測(cè)試風(fēng)格中的哪種。 覆蓋測(cè)試 自動(dòng)化測(cè)試的覆蓋率是一個(gè)有爭(zhēng)議的話題。一些人認(rèn)為它給出了錯(cuò)誤的保證是一個(gè)毫無意義的度量，其他人認(rèn)為它很有用。在我看在，我建議如果你已經(jīng)使用自動(dòng)化測(cè)試但從來沒有檢查過你的測(cè)試覆蓋率，現(xiàn)在做這樣一個(gè)練習(xí)。 使用py.test，我們可以使用Ned Batchelder的覆蓋測(cè)試工具。使用pip安裝pytest-cov。如果你之前這樣運(yùn)行你的測(cè)試： 你可以通過傳遞一些新的標(biāo)識(shí)生成覆蓋率報(bào)告，下面是運(yùn)行sandman的一個(gè)例子： 當(dāng)然不是所有項(xiàng)目都有100%的測(cè)試覆蓋率（事實(shí)上，正如你讀到的，sandman沒有100%覆蓋），但獲得100%的覆蓋率是一個(gè)有用的練習(xí)。它能夠揭示我之前沒有留意的缺陷與重構(gòu)機(jī)會(huì)。 因?yàn)椋鳛闇y(cè)試本身，自動(dòng)生成的測(cè)試覆蓋報(bào)可以作為你持續(xù)集成的一部分。如果你選擇這樣做，部署一個(gè)標(biāo)記來顯示當(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ì)的問題是兼容性。如果你的目標(biāo)是同時(shí)支持Python 2.x和Python 3.x（如果你目前只支持Python 2.x，應(yīng)該這樣做），實(shí)際中你如何確保你的項(xiàng)目支持你所說的所有版本呢？畢竟，當(dāng)你運(yùn)行測(cè)試時(shí)，你只使用特定的版本環(huán)境來運(yùn)行測(cè)試，它很可能在Python2.7.5中運(yùn)行良好但在Python 2.6和3.3出現(xiàn)問題。 幸運(yùn)的是有一個(gè)工具致力于解決這個(gè)問題。tox提供了“Python的標(biāo)準(zhǔn)化測(cè)試”，它不僅僅是在多個(gè)版本環(huán)境中運(yùn)行你的測(cè)試。它創(chuàng)造了一個(gè)完整的沙箱環(huán)境，在這個(gè)環(huán)境中你的包和需求被安裝和測(cè)試。如果你做了更改在測(cè)試時(shí)沒有異常，但意外地影響了安裝，使用Tox你會(huì)發(fā)現(xiàn)這類問題。 通過一個(gè).ini文件配置tox：tox.ini。它是一個(gè)很容易配置的文件，下面是從tox文檔中摘出來的一個(gè)最小化配置的tox.ini： 通過設(shè)置envlist為py26和py27，tox知道需要在這兩種版本環(huán)境下運(yùn)行測(cè)試。tox大約支持十幾個(gè)“默認(rèn)”的環(huán)境沙箱，包括jython和pypy。tox這個(gè)強(qiáng)大的工具使用不同的版本進(jìn)行測(cè)試，在不支持多版本時(shí)可配置警示。 deps是你的包依賴列表。你甚至可以讓tox從PyPI地址安裝所有或一些你依賴包。顯然，相當(dāng)多的想法和工作已融入了項(xiàng)目。 實(shí)際在你的所有環(huán)境下運(yùn)行測(cè)試現(xiàn)在只需要四個(gè)按鍵： 一個(gè)更復(fù)雜的設(shè)置 我的書——“寫地道的Python”，實(shí)際上寫的是一系列的Python模塊和代碼。這樣做是為了確保所有的示例代碼按預(yù)期工作。作為我的構(gòu)建過程的一部分，我運(yùn)行tox來確保任何新的語法代碼能正常運(yùn)行。我偶爾也看看我的測(cè)試覆蓋率，以確保沒有語法在測(cè)試中被無意跳過。因此，我的tox.ini比上面的復(fù)雜一些，一起來看一看： 這個(gè)配置文件依舊比較簡單。而結(jié)果呢？ （我從輸出列表里截取了一部分）。如果想看我的測(cè)試對(duì)一個(gè)環(huán)境的覆蓋率，只需運(yùn)行： 結(jié)果很可怕啊。 setuptools整合 tox可以和setuptools整合，這樣python的setup.py測(cè)試可以運(yùn)行你的tox測(cè)試。將下面的代碼段放到你的setup.py文件里，這段代碼是直接從tox的文檔里拿來的： 現(xiàn)在Python的setup.py測(cè)試將下載tox并運(yùn)行它。真的很酷并且很節(jié)省時(shí)間。 Sphinx文檔生成器 Sphinx是由pocoo團(tuán)隊(duì)開發(fā)的工具[@Lesus 注：pocoo團(tuán)隊(duì)開發(fā)了很多優(yōu)秀的產(chǎn)品：如Flask, Jinja2等等]。它已經(jīng)用來生成Python官方文檔和大多數(shù)流行的Python包的文檔。它以更容易的方式從Python代碼中自動(dòng)產(chǎn)生Python文檔。 使用它完成工作 Sphinx不用了解Python程序以及怎樣從它們中提取出來。它只能翻譯reStructuredText文件，也就意味著你的代碼文檔的reStructuredText譯文需要讓Sphinx知道才能工作，但是管理維護(hù)所有的.py文件[至少是函數(shù)和類的部分]的reStructuredText譯文顯然是不可行的。 幸運(yùn)的是，Sphinx有一個(gè)類似javadoc的擴(kuò)展，叫做autodoc,可以用來從你的代碼文檔中萃取出reStructuredText。為了能夠充分利用Sphinx和autodoc的能力，你需要以一種特別的方式格式化你的文檔。特別是，你需要使用Sphinx的Python指令時(shí)。這里就是使用reStructuredText指令來為一個(gè)函數(shù)生成文檔，使輸出結(jié)果的HTML文檔更漂亮： 文檔需要花費(fèi)一點(diǎn)功夫，但是為了你的使用者，這個(gè)付出是值得的。好吧，好的文檔使一個(gè)可用的項(xiàng)目去其糟粕。 Sphinx的autodoc擴(kuò)展讓我們可以使用很多指令，而這些指令可以自動(dòng)的從你文檔中生成文檔。 安裝 確認(rèn)將Sphinx安裝在你的virtualenv內(nèi)，因?yàn)槲臋n在項(xiàng)目里也是按版本來的。Sphinx不同的版本可能會(huì)產(chǎn)生不同的HTML輸出。通過將其安裝在你的virtualenv內(nèi)，你可以以受控的方式升級(jí)你的文檔。 我們要保持我們的文檔在docs文件夾，將文檔生成到docs/generated文件夾。在項(xiàng)目的根目錄運(yùn)行以下命令將根據(jù)你的文檔字符自動(dòng)重構(gòu)文本文檔： 這將產(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是最簡單的保持更新的方法），否則sphinx-apidoc無法找到你的包。 配置:conf.py conf.py文件創(chuàng)建用來控制產(chǎn)生的文檔的各個(gè)方面。它自己會(huì)很好生成文檔，所以我只簡單地觸及兩點(diǎn)。 版本和發(fā)布 首先，確保你的版本和發(fā)布版本號(hào)保持最新。這些數(shù)字會(huì)作為生成的文檔的一部分顯示，所以你不希望它們遠(yuǎn)離了實(shí)際值。 保持你的版本最新的最簡單方式就是在你的文檔和setup.py文件中都從你的包的__version__屬性讀取。我從Flask的conf.py借用過來配置sandman的conf.py： 這就是說，為了讓文檔產(chǎn)生正確的版本號(hào)，你只需在你的項(xiàng)目的虛擬環(huán)境中簡單的需要運(yùn)行$python setup.py develop即可。現(xiàn)在你只需擔(dān)心保持__version__為最新，因?yàn)閟etup.py會(huì)使用它。 html_theme 考慮到更改default到html_theme，我更喜歡原生態(tài)的東西，顯然這是一個(gè)個(gè)人喜好的問題。我之所以提出這個(gè)問題是因?yàn)镻ython官方文檔在Python 2和Python 3將默認(rèn)主題更改為Pydoc主題（后者的主題是一個(gè)自定義主題僅在CPython源代碼中可用）。對(duì)一些人來說，默認(rèn)的主題使一個(gè)項(xiàng)目看起來“老”一些。 PyPI PyPI，Python包索引（以前被稱為“Cheeseshop”）是一個(gè)公開可用的Python包中央數(shù)據(jù)庫。PyPI是你的項(xiàng)目發(fā)布的地方。一旦你的包（及其相關(guān)的元數(shù)據(jù)）上傳到PyPI，別人通過pip或easy_instal可以下載并安裝它。這一點(diǎn)得強(qiáng)調(diào)一下：即使你的項(xiàng)目托管在GitHub，直到被上傳到PyPI后你的項(xiàng)目才是有用的。當(dāng)然，有些人可以復(fù)制你的git庫任何直接手工安裝它，但更多的人想使用pip來安裝它。 最后的一步 如果你已經(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ò)或者有沒有忘記為一個(gè)文件制作文檔。我建議在上傳每個(gè)項(xiàng)目到PyPI之前運(yùn)行一下它，而不僅只是第一個(gè)。 初始化上傳 現(xiàn)在，你已經(jīng)確定了你的代碼不是垃圾和當(dāng)人們安裝它時(shí)不會(huì)崩潰，讓我們把你的包放到PyPI上吧！你將會(huì)通過setuptools和setup.py腳本交互。如果這是第一次上傳到PyPI，你將首先注冊(cè)它： 注意：如果你還沒有一個(gè)免費(fèi)的PyPI賬戶，你將需要現(xiàn)在去注冊(cè)一個(gè)，才能注冊(cè)這個(gè)包[@Lesus 注：注冊(cè)之后還需要到郵箱去驗(yàn)證才行]。在你已使用了上面注冊(cè)之后，你就可以創(chuàng)建發(fā)布包和上傳到PyPI了: 上面這個(gè)命令建立一個(gè)源碼發(fā)布版(sdist)，然后上傳到PyPI.如果你的包不是純粹的Python（也就是說，你有二進(jìn)制需要編譯進(jìn)去），你就需要發(fā)布一個(gè)二進(jìn)制版，請(qǐng)看setuptools文檔，了解更多。 發(fā)布及版本號(hào) PyPI使用發(fā)行版本模型來確定你軟件包的哪個(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è)新版本。 工作流 將你的第一個(gè)發(fā)布版本上傳到PyPI后，基本的工作流程如下：
用戶希望你保持足夠的更新頻率以修復(fù)bug。你要管理好你的版本號(hào)，不要“過于頻繁”的發(fā)布。記?。耗愕挠脩舨粫?huì)手工維護(hù)他們每個(gè)安裝模塊的不同的版本。 使用TravisCI持續(xù)集成 持續(xù)集成是指一個(gè)項(xiàng)目中所有變化不斷整合的過程（不是周期性的批量更新）。就我們而言，這意味每次我們GitHub提交時(shí)，我們通過測(cè)試運(yùn)行來發(fā)現(xiàn)是否有什么異常，正如你想象的，這是一個(gè)非常有價(jià)值的實(shí)踐。不要有“忘記運(yùn)行測(cè)試”的提交。如果你的提交通不過測(cè)試，你將收到一封電子郵件被告知。 TravisCI是一種使GitHub項(xiàng)目持續(xù)集成更容易的服務(wù)。如果你還沒有賬號(hào)到這看一下注冊(cè)一個(gè)，完成這些之后，在我們進(jìn)入CI之前我們先需要?jiǎng)?chuàng)建一個(gè)簡單的文件。 通過.travis.yml配置 在TravisCI上的不同項(xiàng)目通過一個(gè).travis.yml文件來配置，這個(gè)文件在項(xiàng)目的根目錄。簡要地說，我們需要告訴Travis：
這些都是很直接的東西。下面是sandman.travis.yml的內(nèi)容： 在列出語言和版本后，我們告訴Travis如何安裝我們的包。在install這行，確認(rèn)包含下面這行： 這是pip安裝我們項(xiàng)目的要求（如果有必要的話使用PyPI鏡像站點(diǎn)）。另外的兩行內(nèi)容是sandman特有的。它使用一個(gè)額外的服務(wù)（coveralls.io）來連續(xù)監(jiān)測(cè)測(cè)試用例的覆蓋率，這不是所有項(xiàng)目都需要的。 script：列出能運(yùn)行該項(xiàng)目測(cè)試的命令。與上面一樣，sandman還需要做一些額外的工作。你的項(xiàng)目需要的只有Python的setup.py測(cè)試，after_success部分也可以一塊刪掉。 一旦你提交了這個(gè)文件并在TravisCI中激活了你的項(xiàng)目的，push到GitHub。一會(huì)兒后，你會(huì)看到一個(gè)基于你最近提交的編譯結(jié)束結(jié)果。如果成功了，你的編譯呈現(xiàn)“綠色”和并且狀態(tài)頁會(huì)顯示編譯通過。你可以看到你項(xiàng)目在任何時(shí)間的編譯歷史。這對(duì)對(duì)人開發(fā)特別有用，在歷史頁可以看到特定開發(fā)者出錯(cuò)和編譯的頻率… 你還會(huì)收到一封通知你編譯成功的電子郵件。當(dāng)然你也可以設(shè)置只有在出錯(cuò)或錯(cuò)誤被修復(fù)時(shí)才有郵件通知，但編譯輸出結(jié)果相同時(shí)也不會(huì)發(fā)送。這是非常有用的，你在不必被無用的“編譯通過！”郵件淹沒的同時(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 代碼庫。選擇合適的代碼庫，做一些小幅的配置，那么你的文檔就會(huì)在你每次提交到GitHub之后自動(dòng)重新生成。 配置你的項(xiàng)目應(yīng)該是一個(gè)很直觀的事情。只有一些事需要記住，盡管，這里有一個(gè)配置字段的列表，對(duì)應(yīng)的值可能不一定是你直接用得上的：
DRY 不要重復(fù)你自己 現(xiàn)在你已經(jīng)完成了對(duì)于一個(gè)現(xiàn)存代碼基礎(chǔ)的所有艱難的開源工作，你可能不會(huì)想在開始一個(gè)新項(xiàng)目的時(shí)候把這些事重來一遍。幸運(yùn)的是，你并不需要這么做。有Andrey Roy的Cookiecutter工具（我連接到了Python版本，盡管還有一些不同語言的版本在the main repo)） Cookiecutter是一個(gè)命令行工具能夠自動(dòng)執(zhí)行新建項(xiàng)目的一些步驟來做這篇文章里提到的一些事情。 Daniel Greenfeld (@pydanny )寫了一篇很好的關(guān)于它的博客并且提到了如何與這篇文章里提到的實(shí)踐聯(lián)系上。你可以從這里看看這篇文章： Cookiecutter: Project Templates Made Easy . 結(jié)論 我們已經(jīng)介紹了所有用來開源一個(gè)Python包的命令，工具和服務(wù)。當(dāng)然，你可以直接把它扔到GitHub上并且說“自己安裝它”，但是沒人會(huì)這么做。并且你僅僅是開發(fā)源代碼并不算是真正的開源軟件。 另外，你可能不會(huì)為你的項(xiàng)目吸引外部貢獻(xiàn)者。通過這里列出的方法來設(shè)立你的項(xiàng)目，你就已經(jīng)創(chuàng)建了一個(gè)容易維護(hù)的Python包并且會(huì)鼓勵(lì)大家來使用和貢獻(xiàn)代碼。而這，就是開源軟件的真正精神，不是嗎？ |
|
|
