tl.pkg

tl.pkg是一個命名空間的Python包與獅身人面像文檔模板。
這個包生成的Python包的基本的文件和目錄佈局與獅身人面像文檔和開發擴建。它由兩部分組成：
- 一個paste.script模板創建樣板的Python包，住在命名空間中的一個水平，
- 用於配置獅身人面像，以及必要的軟件包的依賴以及一些主題化的Python模塊。
包裝工程與Python 2.6和2.7。
用法
為了使貼紙模板可用，安裝tl.pkg那裡貼紙可以找到它。然後運行貼紙：
＆NBSP;貼紙創建--template TL-PKG
這將生成樣板的雞蛋分發，完成與zc.buildout配置中，獅身人面像包文檔的骨架，並初始化一個Mercurial庫。該擴建的配置是針對發展，所以它會安裝一個的TestRunner在斌/測試和斌/ DOC文檔，一個建設者。
一些變量將被提示，其中一行的描述和一些關鍵字的包。
個性化
三個變量貼紙會要求您提供用於個性化的方案框架也將產生。這些變量也可以有一個名為文件$ HOME / .TL-pkg.cfg讀取的，如果它存在默認值。文件需要遵循ini文件的語法所理解Python的ConfigParser和含有一個部分（具有一個任意名稱迄今），它定義任何下列變量：
筆者：您的全名。這會出現在包元數據和文檔，以及在產生任何Python文件的版權聲明。
作者-郵件：您的E-mail地址。這似乎無論是在包的元數據和文檔。
到位桶名稱：您的用戶到位桶的名字。這被用來構建屬於該項目的各種網址。目前，假設是，該項目託管在，並在包元數據和文檔點的任何URL到合適的項目到位桶的頁面。
包裝內容
這是為了解釋所生成的文件和目錄的目的，連同建議哪些文件進行編輯時。許多文件將不再需要在所有進行編輯。
Python發行
setup.py：包定義和元數據。更新此文件中至少每當包的版本號，依賴，進入點改變。
：源代碼包樹。不要修改該命名空間包的__init__.py文件，以免其他包在同一個命名空間無法導入。
Mercurial庫
.hg：已創建包時，Mercurial庫已被初始化。生成的文件還沒有被提交。
.hg / hgrc：庫配置指向包在一些水銀託管將來的URL，如果有的話。它還設置你的汞的用戶名。
.hgignore：文件和目錄由水銀被忽略。這包括本地配置和東西預計將擴建，建立文檔或程序包的版本生成的。它不包括Python中生成的文件（如：*。pyc文件），分發（* .egg-INFO），或其他更普遍的工具，如編輯器，這是不特定於這個項目。這樣的模式應該是默認的Mercurial忽略列表。
開發擴建
bootstrap.py：創建的bin /擴建腳本。用同樣的Python解釋器，擴建應使用運行此。無需過編輯這個文件。
buildout.cfg：創建一個測試運行，並為包一個文檔生成器的一個工作擴建配置。包本身被包括作為一個發展雞蛋和附加件被配置為使用任何其他的包僅被釘扎的版本。編輯這個配置包的官方發展擴建，但把當地的定制的local.cfg。版本pinnings進去版本/ versions.cfg，而該文件的版本部分應只撤消聲明培養雞蛋同一文件的擴建部分包pinnings。
local.cfg：在擴建的配置是不感興趣的其他開發本地的定制。這是由水銀忽略。如果更改了此文件，運行斌/擴建-c local.cfg從那時起。雖然這聽起來很麻煩，首先，保持非本地配置在buildout.cfg和版本控制下為用例如連續集成服務器上測試該包重要。
版本/ versions.cfg：
＆NBSP;版本為牽制所用的擴建任何包是不是Zope的工具包的一部分。 tl.pkg的這是需要建立文檔的版本被固定到創建的包文件的版本相同。當後來升級tl.pkg，這個版本寄託的需求將隨著該版本之間的包模板中被修改的文件更新。編輯這個文件，以針通過你的包或擴建所需的任何雞蛋的版本。
版本/ ZTK-版本，X.Y.Z.cfg：
＆NBSP; Zope的工具包中固定的發布，包括在我們的版本pinnings。保持這一個本地副本允許建設沒有網絡接入的擴建。不要修改此文件。
總包文檔
還有一些文本文件，在包的頂級目錄被發現含有標準件的文檔，因此預計在那個地方，在其特定的名稱，以及需要在獅身人面像訪問獨立。這些文件需要，因為它們是由獅身人面像建立完整的文檔時，除了其中包括逐字版權聲明和許可證文本處理，有效的重組文本。
README.txt文件：的包的目的，內容和用法的概述，這將是文檔的索引頁的頁面的PyPI和組成部分。這應該是跟上最新在任何時候包內容。
CHANGES.txt：需要與相關的包的用戶的任何改變包進行更新的更改日誌。該文件的格式是由zest.releaser和它的當前版本（即“尖”的版本在公共Mercurial庫）將從PyPI上頁和內置包文檔指出的理解。
ABOUT.txt：關於包裝和它的作者，如後者的電子郵件地址和包的文檔的URL，網頁的PyPI，問題跟踪和源代碼，以及當前日誌的一些指針。據推測，文件將被無論是在PyPI中，並在公佈;你應該確保使用分配給您的項目的正確網址分別。
COPYRIGHT.txt：版權信息的包：版權持有人，包括版權年，關於所使用的許可證，這是Zope的公共許可證2.1版在默認情況下一些建議。編輯該至少更新年。
LICENSE.TXT：使用許可證的正式文本的副本。不要編輯此除了換取不同的許可證。
完整的文檔，內置使用獅身人面像
商務部：一切，僅僅是相關的獅身人面像，生成的文檔。我們使用後綴名為.txt的獅身人面像輸入文件。而對於doc目錄中的內容存在的一些公約，沒有什麼大不了的事情，如果你隨意修改包的休息;只要確保它仍然有效獅身人面像的輸入。
DOC / conf.py：獅身人面像的配置。基本上所有的配置值遵循慣例，因此從tl.pkg進口的，所以你必須保持完好tl.pkg.sphinxconf的進口和調用。你必須編輯這個文件，如果你想改變一些關於元數據或文檔的只是這個包的外觀。更新到約定獅身人面像生成的文檔將通過升級tl.pkg收購。
DOC /看到index.txt：文檔的頭版。它包括從頂層README.txt文件和目錄指向完整文檔的各部分表中的包的概述。這些措施包括生成API文檔，關於包和更改日誌的一些元數據信息。如果你想添加的頂層部分，例如編輯這個文件。
DOC / narrative.txt：
＆NBSP;敘事包文件的根文件。這是為了收集任何駐留在你的源代碼樹的Python模塊中的doc-測試文件。你需要列出下toctree指令的文件，其文件名是格局 - <文件名>（不帶.txt後綴）。一個註釋掉的示例文件清單也包括在內。
DOC / api.txt：生成的API文檔的根文件。該API文檔是半自動的，你必須在這個文件中列出，在自動摘要指令，將記錄所有的模塊，從那時起自動發生。一個註釋掉的示例模塊房源被包括在內。
DOC / OVERVIEW.TXT：
＆NBSP; A存根包括頂級readme.txt文件。無需編輯該文件。
DOC / about.txt：關於包的元信息，結合頂層文件ABOUT.txt，COPYRIGHT.txt和LICENSE.TXT。你不會需要編輯這個文件。
DOC / changes.txt：
＆NBSP; A存根包括頂層文件CHANGES.txt。無需編輯該文件。
DOC / requirements.pip：
＆NBSP; Python的雞蛋的上市打造的文件要求（比獅身人面像本身除外）。這意味著，在建築的文檔。你需要與他們為了能夠使用由tl.pkg實現的約定列入白名單。編輯這個文件時，您的文檔的包依賴關係變化;你不能用雞蛋演員在這裡。
構建完整的文檔
生成的擴建配置在斌/ DOC調用獅身人面像建造的文件安裝的腳本。要運行此腳本，當前工作目錄必須是包根。該腳本會將內置文檔進編譯/ DOC /（相對於包的頂級目錄）。傳遞給斌/ DOC選項將在底層獅身人面像-build命令過去了，但請注意，位置參數將無法正常工作。
獅身人面像的配置值
默認情況下，一些獅身人面像的擴展被啟用，所以你可能想在除了核心獅身人面像變量配置這些：
- sphinx.ext.autosummary
- sphinx.ext.viewcode
- sphinx.ext.inheritance_diagram
- sphinxcontrib.cheeseshop
- sphinxcontrib.issuetracker
你可以通過簡單的設置在conf.py.各自變量覆蓋從tl.pkg默認tl.pkg.sphinxconf.set_defaults的調用需要發生在最後：
source_suffix ='.foo'
進口tl.pkg.sphinxconf
tl.pkg.sphinxconf.set_defaults（）
相反，sphinxconf嘗試使用變量從conf.py計算值。如果指定了這些變量，那也必須做set_defaults調用之前。目前，該變量如下：
_year_started：項目啟動一年的可選值。此默認為當前年（在文檔的建設時間），但如果它被指定，並從當年不同，它是用來構建像“2001至2012年著有”版權聲明。
_flattr_url：如果指定，這被認為是一個flattr的事情這個項目，並捐贈flattr的按鈕將出現在完整文檔的菜單欄​​頂部的URL。添加flattr的按鈕的PyPI頁，取消“支持項目”項ABOUT.txt並填寫網址那裡。
_issuetracker_offline：
＆NBSP;如果設置為true值，該sphinxcontrib-issuetracker一體化的整合到位桶會被修改，以便建立文檔和獅身人面像運行時，它不會試圖訪問服務器保持獨立的網絡接入。 （與其他跟踪器整合一直沒有照顧至今。）這將禁用跟踪器集成一些功能，但保留，例如，認識到純文本的問題號碼issuetracker擴展的能力。
最後，tl.pkg.sphinxconf模塊定義，你可以調用註冊模擬模塊，如果文件是要建一個系統上，如函數無法安裝某些代碼（如模塊用C實現的）：
tl.pkg.sphinxconf.register_mock_modules（“開羅”，“圖形對象”，“GTK'）