tl.pkg

tl.pkg is 'n templaat vir 'n namespaced Python pakket met Sphinx docs.
Hierdie pakket genereer die basiese lêer en gids uitleg van Python pakkette met Sphinx dokumentasie en 'n ontwikkeling buildout. Dit bestaan ​​uit twee dele:
- 'N paste.script sjabloon wat skep die boiler vir 'n Python pakket wat in een vlak van naamruimte woon, en
- 'N Python module wat gebruik word Sphinx te stel, saam met die nodige pakket afhanklikhede en sommige thematisering.
Die pakket werk met Python 2.6 en 2.7.
Gebruik
Maak die paster sjabloon beskikbaar is, installeer tl.pkg waar paster dit kan kry. Dan loop paster:
& Nbsp;. Paster skep --template tl-pkg
Dit sal die boiler vir 'n eier verspreiding, kompleet met zc.buildout opset, die geraamte van Sphinx pakket dokumentasie, en 'n kwik bewaarplek geïnisialiseer genereer. Die buildout opset is gemik op die ontwikkeling, so dit sal 'n testrunner by bin / toets en 'n dokumentasie bouer by bin / doc installeer.
'N Paar veranderlikes sal gevra word vir, onder hulle 'n een-lyn beskrywing en 'n paar sleutelwoorde vir die pakket.
Personalisation
Drie veranderlikes wat paster jou vra word gebruik om die pakket geraamte dit sal genereer aan te pas. Hierdie veranderlikes kan hê standaard waardes wat gelees word van 'n lêer met die naam $ HOME / .tl-pkg.cfg indien dit bestaan. Die lêer moet ini-lêer sintaksis te volg soos verstaan ​​deur Python se ConfigParser en bevat een afdeling (met 'n arbitrêre naam so ver) wat bepaal enige van die volgende veranderlikes:
skrywer: Jou volle naam. Dit sal in die pakket metadata en dokumentasie, asook in die kopiereg van enige Python lêers gegenereer.
skrywer-e-pos: Jou e-pos adres. Dit blyk beide in die pakket metadata en dokumentasie.
bitbucket-naam: Jou bitbucket gebruiker naam. Dit word gebruik om die verskillende URLs wat aan die projek te bou. Op die oomblik is, die aanname is dat die projek word gehuisves by en enige URL's in die pakket metadata en dokumentasie punt toe te eien bladsye van daardie bitbucket projek.
pakket inhoud
Dit is die doel van die gegenereerde lêers en dopgehou te verduidelik, saam met advies oor watter lêers te wysig wanneer. Baie lêers sal nie nodig geredigeer te word nie.
Python verspreiding
setup.py: Die pakket definisie en metadata. Werk hierdie lêer ten minste wanneer die pakket se weergawe nommer, afhanklikhede, inskrywing punte verander.
: Die bron-kode boom van die pakket. Moenie die naamruimte pakket se __init__.py lêer verander nie sodat ander pakkette in dieselfde naamruimte kan nie ingevoer word nie.
Kwik bewaarplek
.hg: Die Mercurial bewaarplek is reeds geïnisieer wanneer die pakket is geskep. Die gegenereerde lêers is nie verbind nie.
.hg / hgrc: Repository opset wat verwys na die toekoms URL van die pakket in sommige Mercurial hosting, indien enige. Dit sit ook jou HG gebruiker naam.
.hgignore: lêers en dopgehou om geïgnoreer te word deur Mercurial. Dit sluit in plaaslike opset en dinge verwag te word gegenereer deur buildout, dokumentasie bou of pakket vrystellings. Dit sluit nie die lêers (soos * .pyc) wat gegenereer word deur Python, versprei (* .egg-inligting), of ander meer algemene gereedskap soos jou redakteur, wat nie spesifiek vir hierdie projek. Sulke patrone moet wees op jou standaard Mercurial ignoreer lys.
Ontwikkeling buildout
bootstrap.py: Skep die bin / buildout script. Begin dit met dieselfde Python tolk wat buildout moet gebruik. Geen behoefte om ooit hierdie lêer wysig.
buildout.cfg: 'n werk buildout opset wat skep 'n toets naaswenner en 'n dokumentasie bouer vir die pakket. Die pakket self word as 'n ontwikkeling eier en buildout is ingestel net vasgesteek weergawes van enige ander pakkette te gebruik. Wysig hierdie die pakket se amptelike ontwikkeling buildout te stel, maar het plaaslike customisations in local.cfg. Weergawe pinnings gaan in weergawes / versions.cfg terwyl hierdie lêer se weergawes artikel moet slegs pinnings van pakkette wat verklaar is ontwikkel eiers deur dieselfde lêer se buildout artikel ongedaan te maak.
local.cfg: Plaaslike customisations van die buildout opset wat van geen belang vir ander ontwikkelaars. Dit word geïgnoreer deur Mercurial. As jy hierdie lêer verander, hardloop bin / buildout-c local.cfg van toe af. Hoewel dit mag klink lomp op die eerste, die behoud van die nie-plaaslike opset in buildout.cfg en onder weergawe beheer is belangrik vir gebruik gevalle soos die toets van die pakket op 'n deurlopende-integrasie bediener.
weergawes / versions.cfg:
& Nbsp; Weergawe pinning vir enige pakkette wat gebruik word deur die buildout wat nie deel is van die Zope toolkit. Die weergawe van tl.pkg wat nodig is vir die bou van die dokumentasie is vasgepen op dieselfde weergawe wat die pakket lêers geskep. Wanneer die opgradering tl.pkg later, is hierdie weergawe pinning behoeftes om saam opgedateer word met enige lêers wat in die pakket sjabloon tussen die weergawes verander het. Wysig hierdie lêer weergawes van enige eiers wat deur jou pakket of jou buildout te pen.
weergawes / ztk-weergawes-X.Y.Z.cfg:
& Nbsp; 'n vaste vrylating van die Zope toolkit, ingesluit in ons weergawe pinnings. Hou 'n plaaslike kopie van hierdie laat bou die buildout sonder toegang tot die netwerk. Moenie hierdie lêer wysig nie.
Algemene pakket dokumentasie
Daar is 'n aantal van die teks lêers te vinde in die pakket se top-vlak gids wat standaard stukke van die dokumentasie bevat en dus in daardie plek en onder hul spesifieke name wat verwag is, en wat nodig toeganklik onafhanklik van Sphinx te wees. Hierdie lêers moet geldig herstruktureer teks soos hulle word verwerk deur Sphinx wanneer die bou van die volledige dokumentasie, behalwe vir die kopiereg kennisgewing en lisensie teks wat woordeliks ingesluit is om te wees.
Readme.txt: 'n oorsig van die pakket se doel, inhoud en gebruik wat deel van sy PyPI bladsy en van die dokumentasie indeks bladsy wees. Dit moet gehou word up-to-date met die pakket inhoud te alle tye.
CHANGES.txt: Die verandering log wat opgedateer word met enige veranderinge aan die pakket wat betrekking het op die gebruikers van die pakket moet word. Die lêer se formaat word verstaan ​​deur zest.releaser en die huidige weergawe van dit (dws die "tip" weergawe in die openbare Mercurial bewaarplek) sal uitgewys word uit die PyPI bladsy en die gebou pakket dokumentasie.
ABOUT.txt: Sommige wenke oor die pakket en die skrywers, soos die laasgenoemde se e-pos adres en die URLs van die pakket se dokumentasie, PyPI bladsy issue tracker en bron-kode, sowel as die huidige log. Daar word aanvaar dat dokumentasie sal word gepubliseer word sowel by PyPI en by ; moet jy seker die korrekte onderskeie URLs wat aan jou projek te gebruik maak.
COPYRIGHT.txt: Kopiereg inligting vir die pakket: outeursreghouer insluitend die kopiereg jaar en 'n paar advies oor die lisensie gebruik, wat is die Zope openbare lisensie, weergawe 2.1 deur verstek. Wysig dit ten minste die jaar te werk.
License.txt: 'n afskrif van die amptelike teks van die lisensie gebruik. Wysig nie hierdie as dit te ruil vir 'n ander lisensie.
Volledige dokumentasie, gebou met behulp Sphinx
Doc: Alles wat slegs relevant tot die Sphinx-gegenereerde dokumentasie. Ons gebruik die agtervoegsel txt vir Sphinx invoer lêers. Terwyl 'n aantal konvensies bestaan ​​vir die inhoud van die doc gids, sal niks sleg gebeur met die res van die pakket as jy dit vrylik verander; net maak seker dit bly geldig Sphinx insette.
doc / conf.py: Sphinx opset. Basies al die opset waardes volg konvensies en word dus ingevoer uit tl.pkg, sodat jy moet die invoer en oproep van tl.pkg.sphinxconf ongeskonde hou. Jy het hierdie lêer wysig as jy wil iets oor die metadata of die voorkoms van die dokumentasie net vir hierdie pakket te verander. Updates die konvensies vir Sphinx-gegenereerde dokumentasie sal verkry word deur die opgradering tl.pkg.
doc / index.txt: Die voorblad van die dokumentasie. Dit sluit in die pakket oorsig van die top-vlak readme.txt lêer en 'n tafel van die inhoud te wys op die dele van die volledige dokumentasie. Dit sluit gegenereer API dokumentasie, sommige meta inligting oor die pakket en die verandering log. Wysig hierdie lêer as jy wil top-vlak afdelings by te voeg, byvoorbeeld.
doc / narrative.txt:
& Nbsp; Die wortel dokument van die verhaal pakket dokumentasie. Dit is bedoel om 'n doc-toets lêers wat onder die Python modules in jou bron boom woon in te samel. Jy moet die lêers te lys onder die toctree richtlijn hul dokument name van die patroon -. (sonder die Txt agtervoegsel). A kommentaar-out voorbeeld lêer lys is ingesluit.
doc / api.txt: Die wortel dokument van die gegenereerde API dokumentasie. Die API is semi-outomaties in wat jy het om te lys in hierdie lêer, onder die autosummary richtlijn, al die modules gedokumenteer word, wat outomaties gebeur van toe af gedokumenteer. A kommentaar-out byvoorbeeld module lys is ingesluit.
doc / Overview.txt:
& Nbsp; 'n stomp die top-vlak lêer readme.txt in te sluit. Geen behoefte om die lêer te wysig.
doc / about.txt: Meta inligting oor die pakket, 'n kombinasie van die top-vlak lêers ABOUT.txt, COPYRIGHT.txt en license.txt. Jy sal nie nodig om die lêer te wysig.
doc / changes.txt:
& Nbsp; 'n stomp die top-vlak lêer CHANGES.txt te sluit. Geen behoefte om die lêer te wysig.
doc / requirements.pip:
& Nbsp; 'n lys van 'n afgestorwene eiers (behalwe Sphinx self) vereis om die dokumentasie te bou. Dit is bedoel vir die bou van die dokumentasie by . Jy moet in staat te wees om die konvensies wat deur tl.pkg te gebruik om die wit lys word met hulle. Wysig hierdie lêer wanneer jou dokumentasie se pakket afhanklikhede verander; jy kan nie eier ekstras gebruik hier.
Die bou van die volledige dokumentasie
Die gegenereerde buildout opset installeer 'n script op bin / doc dat Sphinx noem die dokumentasie te bou. Dit script uit te voer, moet jy jou huidige werk gids die pakket wortel wees. Die script sal die gebou dokumentasie in aanloop / doc / (relatief tot die pakket se top-vlak gids) sit. Opsies wat na bin / doc sal oorgedra word na die onderliggende sfinks-opbou bevel nie, maar wel dat posisionele argumente sal nie werk nie.
Sphinx opset waardes
By verstek, is 'n aantal van Sphinx uitbreidings geaktiveer is, sodat jy dalk wil om dit te stel bykomend tot die kern Sphinx veranderlikes:
- Sphinx.ext.autosummary
- Sphinx.ext.viewcode
- Sphinx.ext.inheritance_diagram
- Sphinxcontrib.cheeseshop
- Sphinxcontrib.issuetracker
Jy kan ignoreer die standaard van tl.pkg deur eenvoudig die opstel van die onderskeie veranderlikes in jou conf.py. Die oproep van tl.pkg.sphinxconf.set_defaults moet gebeur aan die einde:
source_suffix = '.foo'
invoer tl.pkg.sphinxconf
tl.pkg.sphinxconf.set_defaults ()
Aan die ander kant, sphinxconf probeer veranderlikes te gebruik van conf.py waardes te bereken. As hierdie veranderlikes word gespesifiseer, wat ook gedoen word voordat set_defaults genoem word. Tans word die volgende veranderlikes erken:
_year_started: Opsionele waarde vir die jaar het die projek is begin. Hierdie verstek na die huidige jaar (ten tyde van die dokumentasie gebou), maar as dit is gespesifiseer en verskil van die huidige jaar, is dit gebruik om 'n kopieregkennisgewing soos "2001-2012 outeur" te bou.
_flattr_url: As gespesifiseer, dit is veronderstel om die URL van 'n flattr ding vir hierdie projek en flattr skenking knoppies sal verskyn aan die bokant van die spyskaart kolom van die volledige dokumentasie te wees. 'N flattr knoppie by te voeg by die PyPI bladsy Uncomment die "Ondersteun die projek" item in ABOUT.txt en vul in die URL is daar ook.
_issuetracker_offline:
& Nbsp; As stel na 'n ware waarde, die bitbucket integrasie van die sphinxcontrib-issuetracker integrasie sal verander word sodat dit nie sal probeer om die bediener om toegang te verkry wanneer die bou van die dokumentasie en die Sphinx run bly onafhanklik van toegang tot die netwerk. (Integrasie met ander spoorsnyers nie versorg so ver.) Dit sal 'n funksie van die spoorsnyer integrasie afskakel, maar behou, bv, die issuetracker uitbreiding se vermoë plain-text kwessie getalle te herken.
Ten slotte, die tl.pkg.sphinxconf module definieer 'n funksie wat jy kan noem, bespot modules te registreer indien die dokumentasie gebou sal word op 'n stelsel soos wat nie sekere kode kan installeer (soos modules geïmplementeer in C):
tl.pkg.sphinxconf.register_mock_modules ('cairo', 'gobject "," gtk')

Vereistes :

• Python