tl.pkg

tl.pkg je šablona pro namespaced balíček Python s Sphinx dokumenty.
Tento balíček vytváří základní souborů a adresářů rozložení balících Pythonu s Sphinx dokumentaci a rozvojové buildout. Skládá se ze dvou částí:
- Paste.script šablona, ​​která vytváří často používaný pro balíček Pythonu, který žije v jedné úrovni názvů, a
- Python modul, který se používá ke konfiguraci sfinga, spolu s potřebnými závislostmi balíků a některých motivů.
Balíček pracuje s Python 2.6 a 2.7.
Použít
Chcete-li šablona paster k dispozici, nainstalujte tl.pkg kde paster najít. Poté spusťte Paster:
& Nbsp;. Paster vytvořit --template tl-pkg
To bude generovat často používaný i pro distribuci vajec, kompletní s konfigurací zc.buildout, kostry dokumentace balíčku Sphinx a Mercurial úložiště inicializované. Konfigurace buildout je zaměřena na vývoj, tak to bude instalovat testrunner na bin / zkouška a dokumentační stavitel na bin / doc.
Několik proměnné budou vyzváni k, mezi nimi i popis jeden řádek a některá klíčová slova pro balíček.
Přizpůsobení
Další tři proměnné, které paster vám za ptá se používají k přizpůsobení balíček kostru to bude generovat. Tyto proměnné mohou mít výchozí hodnoty, které jsou ze souboru s názvem $ HOME / .tl-pkg.cfg, pokud existuje. Soubor musí následovat syntaxi ini-souboru, jak je chápáno Python ConfigParser a obsahují jednu sekci (s libovolným názvem dosud), který definuje některé z následujících proměnných:
autor: Vaše celé jméno. To se objeví v metadatech balíčku a dokumentaci, jakož i v oznámení o autorských právech jakýchkoliv Python souborů vytvořených.
autor-email: Váš e-mail. To se zdá jak v metadatech balíčku a dokumentace.
Bitbucket-name: Vaše Bitbucket uživatelské jméno. To se používá k vytvoření různých URL, které patří do projektu. V současné době, předpoklad je, že projekt je umístěn na a všechny adresy URL v metadatech balení a dokumentace bodu na příslušné stránky tohoto Bitbucket projektu.
Obsah balení
To je vysvětlit účel vytvořených souborů a adresářů, spolu s radami, na které soubory, které chcete upravit, když. Mnoho souborů není nutné upravovat vůbec.
Distribuce Python
setup.py: Definice balíček a metadata. Aktualizujte tento soubor alespoň kdykoliv číslo verze z balíčku, závislosti, vstupní body změnit.
: Zdrojový kód strom obalu. Neměňte jmenném prostoru balíku __init__.py soubor lest další balíčky ve stejném jmenném prostoru nelze importovat.
Mercurial repository
.hg: Mercurial úložiště je již inicializován, když je balíček byl vytvořen. Vytvořené soubory nebyly přiděleny ještě.
.hg / hgrc: úložiště konfigurace, která odkazuje na budoucí URL balíčku v některých Mercurial hosting, pokud existuje. To také nastaví hg uživatelské jméno.
.hgignore: Soubory a adresáře bude ignorován Mercurial. To zahrnuje místní konfiguraci a tak očekává, že budou generovány buildout, dokumentace staví nebo balíček zprávy. Nezahrnuje soubory vytvořené Python (například * .pyc), distribuovat (* .egg-info), nebo jiné obecnější nástroje, jako je vaše editoru, které nejsou specifické pro tento projekt. Tyto modely by měly být na váš výchozí Mercurial seznam ignorovaných.
Vývoj buildout
bootstrap.py: Vytvoří bin / buildout skript. Běh to se stejnou IRP že buildout by měl používat. Není třeba někdy upravit tento soubor.
buildout.cfg: pracovní konfigurace buildout která vytváří testovací běžec a dokumentace stavitele pro balíček. Balíček sám je zahrnut jako rozvíjet vejce a buildout je nakonfigurován pro použití pouze připnul verze jiných balíků. Upravit to nakonfigurovat balíku oficiální rozvojovou buildout ale dát místní customizace v local.cfg. Verze pinnings jít verzích / versions.cfg zatímco část verze tohoto souboru by měl vrátit pouze pinnings balíčků, které jsou deklarovány vyvíjejí vejce podle sekcí buildout tohoto stejného souboru.
local.cfg: Místní customizace podle konfigurace buildout taková, která mají na ostatní vývojáře nezajímá. Toto je ignorován Mercurial. Změníte-li tento soubor, spusťte bin / buildout -c local.cfg od té doby. I když to může znít na první pohled těžkopádné, udržení non-místní konfiguraci v buildout.cfg a pod kontrolou verzí je důležitá pro případy použití, jako je testování balíčku na kontinuální-Integration Server.
verze / versions.cfg:
& Nbsp; Verze připnout k zásilce používaných buildout, které nejsou součástí sady nástrojů Zope. Verze tl.pkg který je potřebný pro stavbu dokumentace je přitlačen ke stejné verzi, která vytvořila soubory balíčku. Při aktualizaci tl.pkg později, tato verze připnout třeba aktualizovat spolu se všemi soubory, které se změnily v šabloně balíčku mezi verzemi. Editovat tento soubor pin verze veškerých požadovaných balení nebo vaše buildout vejce.
verze / ZTK-verze-X.Y.Z.cfg:
& Nbsp; pevná uvolnění Zope sady nástrojů, která je součástí naší verze pinnings. Vedení místní kopii to umožňuje budování buildout bez přístupu k síti. Nepoužívejte tento soubor upravovat.
Obecná dokumentace balíček
Existuje celá řada textových souborů, které se nacházejí v balíčku v adresáři nejvyšší úrovně, které obsahují standardní kousky dokumentace, a proto se očekává, že na tomto místě a pod jejich konkrétních jmen a které musí být přístupné nezávislý na sfinga. Tyto soubory musí být platný restrukturalizaci znění, jak jsou zpracovávány Sfinga při vytváření kompletní dokumentaci, s výjimkou upozornění na autorská práva a licence textu, které jsou zahrnuty v doslovném znění.
README.txt: Přehled o souborných službách pro jeho účelu, obsahu a využití, které bude součástí jeho stránky PyPI a obsahovou stránku v dokumentaci je. To by mělo být up-to-date s obsahem balení po celou dobu.
CHANGES.txt: Změna protokolu, který je třeba aktualizovat s případnými změnami na obalu, které jsou relevantní pro uživatele balíčku. Formát souboru, je chápán zest.releaser a aktuální verzí toho (tj "špičky" verze ve veřejném Mercurial úložiště), bude poukázal na na stránce PyPI a dokumentace skutečného balíčku.
ABOUT.txt: Některé ukazatele o balíčku a jeho autoři, jako jsou jeho e-mailovou adresu a URL dokumentaci balíku, PyPI stránku, sledování problémů a zdrojového kódu, stejně jako aktuální log. Předpokládá se, že dokumentace bude bude zveřejněn jak na PyPI i na ; měli byste se ujistit, že používáte správné adresy URL přiřazené k projektu.
COPYRIGHT.txt: Informace o autorských právech k balíčku: držitele autorských práv, včetně autorských práv let a radu o povolení použité, což je Zope Public License, verze 2.1 ve výchozím nastavení. Upravit to alespoň k aktualizaci roky.
LICENSE.txt: Kopie oficiálního textu licence použité. Neupravujte to k jiným účelům, vyměnit za jinou licenci.
Kompletní dokumentace, postavený pomocí Sphinx
doc: Všechno, co je relevantní pouze pro Sphinx generované dokumentace. Používáme příponu txt pro vstupní soubory Sphinx. I když existuje řada úmluv obsahu adresáře doc, se nic zlého nestane se zbytkem balíčku, pokud jej libovolně změnit; Jen se ujistěte, že zůstane v platnosti Sphinx vstupu.
doc / conf.py: konfigurace Sphinx. V podstatě všechny konfigurační hodnoty dodržovat konvence, a proto jsou dováženy ze tl.pkg, takže musíte mít dovoz a vzývání tl.pkg.sphinxconf neporušený. Budete muset upravit tento soubor, pokud chcete změnit něco o metadata nebo vzhledu dokumentace právě pro tento balíček. Aktualizace konvencí na Sphinx generované dokumentace, budou získány pomocí upgradu tl.pkg.
doc / index.txt: Přední strana dokumentace. Obsahuje přehled balíček ze souboru README.txt nejvyšší úrovně a obsahu a ukázal na částí kompletní dokumentace. Patří mezi ně vygenerovaný dokumentaci API, nějaká meta informace o balíčku a záznamu změn. Editovat tento soubor, pokud chcete přidat sekce nejvyšší úrovně, například.
doc / narrative.txt:
& Nbsp; kořen dokument dokumentace vyprávění balíčku. Tím se má vybírat nějaké doc-testovací soubory, které jsou umístěny mezi modulů Pythonu ve zdrojovém stromu. Musíte na seznam souborů v rámci směrnice o toctree, jejich jména dokument, který vzor -. (bez přípony TXT). Uvedl-out příklad file výpis je v ceně.
doc / api.txt: kořen dokument dokumentace generované API. API je zdokumentováno poloautomaticky v tom, že musíte uvést v tomto souboru, pod autosummary směrnice, všechny moduly je třeba zdokumentovat, což se děje automaticky z té doby. Uvedl-out příklad modul výpis je v ceně.
doc / overview.txt:
& Nbsp; pahýl zahrnout soubor nejvyšší úrovně souboru readme.txt. Není třeba upravovat tento soubor.
doc / about.txt: Meta informace o balíčku, který kombinuje soubory nejvyšší úrovně ABOUT.txt, COPYRIGHT.txt, a License.txt. Nebudete muset upravit tento soubor.
doc / changes.txt:
& Nbsp; pahýl zahrnout soubor CHANGES.txt nejvyšší úrovně. Není třeba upravovat tento soubor.
doc / requirements.pip:
& Nbsp; výpis z Python vajec (jiné než sfinga sám), potřebné k vytvoření dokumentace. To je určena pro stavební dokumentace na . Budete muset být na bílé listině s nimi tak, aby bylo možné používat konvence uskutečňované tl.pkg. Editovat tento soubor kdykoli změnit závislostí balíků v dokumentaci je; nemůžete použít tu vejce navíc.
Stavební úplnou dokumentaci
Generovaný konfigurace buildout nainstaluje skript na bin / doc, který volá sfinga stavět dokumentaci. Chcete-li spustit tento skript, musí váš aktuální pracovní adresář je kořenový balíček. Skript bude klást vestavěný dokumentaci do build / doc / (vzhledem k balíku adresáře nejvyšší úrovně). Možnosti předány bin / doc budou předány podkladové příkazu sfinga-build, ale berte na vědomí, že poziční argumenty nebude fungovat.
Hodnoty konfigurace Sphinx
Ve výchozím nastavení je počet prodloužení Sphinx, takže možná budete chtít konfigurovat tyto kromě základních Sphinx proměnných:
- Sphinx.ext.autosummary
- Sphinx.ext.viewcode
- Sphinx.ext.inheritance_diagram
- Sphinxcontrib.cheeseshop
- Sphinxcontrib.issuetracker
Můžete přepsat výchozí nastavení z tl.pkg jednoduše nastavením příslušné proměnné v conf.py. Vyvolání tl.pkg.sphinxconf.set_defaults musí stát na konci:
source_suffix = '.foo'
import tl.pkg.sphinxconf
tl.pkg.sphinxconf.set_defaults ()
Naopak, sphinxconf pokusí použít proměnné z conf.py pro výpočet hodnoty. Jsou-li uvedeno tyto proměnné, které musí být rovněž provedena před set_defaults se nazývá. V současné době se tyto proměnné jsou uznány:
_year_started: Volitelná hodnota za rok byl projekt zahájen. Tato výchozí běžného roku (v době, kdy dokumentace stavby), ale pokud je specifikována a liší se od běžného roku, se používá ke konstrukci informace o autorských právech, jako je "2001-2012 autora".
_flattr_url: Je-li uvedeno, toto předpokládá se, že adresa URL Flattr věc pro tento projekt a Flattr dárcovství tlačítka se objeví v horní části menu sloupce kompletní dokumentace. Chcete-li přidat tlačítko Flattr na stránku PyPI, vložte "podporu projektu" položku ABOUT.txt a vyplnit URL i tam.
_issuetracker_offline:
& Nbsp; Pokud je nastaveno na skutečné hodnoty, integrace Bitbucket integrace sphinxcontrib-issuetracker bude upraven tak, že nebude snažit získat přístup k server při vytváření dokumentace a běh Sphinx zůstává nezávislou na přístupu k síti. (Integrace s jinými stopaři nebylo dosud postaráno.) Tím se zakázat některé funkce integrace tracker, ale zachovat, například schopnost issuetracker prodloužení, aby uznala, vydávat čísel plain-text.
A konečně, tl.pkg.sphinxconf modul definuje funkci, která vám mohou volat na registrovat falešné modulů, pokud má být postaven na systému, jako je dokumentace , které nelze nainstalovat určitý kód (jako moduly implementován v C):
tl.pkg.sphinxconf.register_mock_modules ("Káhira", "GObject", "gtk")

Požadavky na :

• Python