tl.pkg

tl.pkg yra už vardų kurie Python paketas su Sphinx docs šablonas.
Šis paketas sukuria pagrindinę failų ir katalogų išdėstymą Python paketų su Sphinx dokumentus ir plėtros Katilinės statyba. Jis susideda iš dviejų dalių:
- Paste.script šablonas, kuris sukuria, kad reikalingas Python paketą, kuris gyvena vienoje lygio vardų Standartiniai ir
- Python modulis, kuris naudojamas konfigūruoti Sfinksas, kartu su būtinų paketų priklausomybių ir kai theming.
Paketas dirba su Python 2.6 ir 2.7.
Naudojimas
Kad Lipdukas šabloną galima, įdiekite tl.pkg kur Lipdukas galite rasti jį. Tada paleiskite Lipdukas:
& Nbsp;. Lipdukas sukurti --template TL-pkg
Tai sukurs už kiaušinių platinimo Standartiniai, visiškai su zc.buildout konfigūraciją, kad Sfinksas paketo dokumentuose skeletas, ir Mercurial saugykloje pradedamas. Katilinės statyba konfigūracija yra skirta vystymuisi, todėl ji bus įdiegti ne bin / bandymo testrunner ir dokumentacijos statybininkas ne bin / doc.
Keletas kintamieji bus pasiūlyta, tarp jų vieno linijos aprašymas ir kai dėl pakuotės raktažodžius.
Stiliaus
Daugiau Trys kintamieji Lipdukas prašo jūsų naudojamos asmeniniams pakuotės skeletas ji sukurs. Šie kintamieji gali turėti reikšmes pagal nutylėjimą, kurie skaityti iš failo pavadinimu $ HOME / .tl-pkg.cfg jei jis egzistuoja. Failą reikia laikytis INI-failo sintaksės kaip suprasti Python'o ConfigParser ir būti vienas skyrių (su savavališkai pavadinimas iki šiol), kuris apibrėžia bet kurį iš šių kintamųjų:
autorius: Jūsų vardas, pavardė. Tai pasirodys pakuotės metaduomenų ir dokumentus, taip pat autorių teisių pranešimus apie bet Python failus generuoja.
autorius-pašto adresas: Jūsų elektroninio pašto adresas. Atrodo, tiek pakuotės metaduomenų ir dokumentus.
bitbucket-vardas: Jūsų bitbucket vartotojo vardas. Tai naudojama statyti įvairius URL priklausančius projektą. Šiuo metu prielaida yra ta, kad projektas yra patalpinta ir bet kokie paketas metaduomenų ir dokumentacijos taško URL pasisavinti puslapius tos bitbucket projektą.
Pakuotės turinys
Tai paaiškinti kuriamą failus ir katalogus tikslą, kartu su pranešimu apie kuriuos failus redaguoti kada. Daug failų nereikia būti redaguojama ne visiems.
Python platinimas
setup.py: paketas apibrėžimas ir metaduomenys. Atnaujinkite šį failą bent kai paketo versijos numeris, priklausomybių, įėjimo taškai pakeisti.
: kodo medis pakuotės. Nekeiskite vardų paketą anketa __init__.py failą Kad kiti paketai toje pačioje vardų, negali būti importuojami.
Mercurial saugykla
.hg: Mercurial saugykloje jau pradedamas, kai paketas buvo sukurtas. Susidariusias failai nebuvo įsipareigojusi dar.
.hg / hgrc: saugykla konfigūracija, atkreipia dėmesį į būsimą URL paketo kai kuriose Mercurial talpinimas, jei tokių yra. Ji taip pat nustato savo hg vartotojo vardą.
.hgignore: Failai ir katalogai turi būti ignoruojamas Mercurial. Tai apima vietos konfigūraciją ir kita tikimasi generuos Katilinės statyba, dokumentacija stato ar paketų spaudai. Tai neapima failus generuoja Python (pvz * .pyc), platinti (* .egg-info) ar kitų bendresnių priemones, pavyzdžiui, jūsų redaktorius, kurie nėra būdingi šiam projektui. Tokie modeliai turėtų būti jūsų numatytoji Mercurial ignoruoti sąrašą.
Plėtros Katilinės statyba
bootstrap.py: Sukuria bin / Katilinės statyba scenarijų. Vykdyti tai su tuo pačiu interpretatoriaus, kad Katilinės statyba turėtų naudoti. Nereikia kada redaguoti šį failą.
buildout.cfg: darbo Katilinės statyba konfigūracijos, kuri sukuria bandomąją bėgikas ir dokumentacijos statybininkas pakuotės. Pati pakuotė būtų įtrauktas kaip sukurti kiaušiniu ir Katilinės statyba sukonfigūruota naudoti tik prisegti versijas kitomis paketai. Redaguoti šį konfigūruoti paketo oficiali vystymosi Katilinės statyba, bet įdėti vietos customisations į local.cfg. Versija pinnings eiti versijų / versions.cfg o šio failo versijų skirsnyje turėtų būti anuliuoti tik pinnings pakuočių, kurios yra deklaruotos kurti kiaušiniai tą pačią failo Katilinės statyba skyriuje.
local.cfg: Vietos customisations apie Katilinės statyba konfigūracijos, kurios nedomina kitų kūrėjų. Tai yra ignoruojami Mercurial. Jei pakeisite šį failą, paleisti bin / Katilinės statyba -c local.cfg nuo tada. Nors tai gali skambėti sudėtinga ne pirmas, išlaikant ne vietos konfigūraciją buildout.cfg ir pagal versijų kontrolę svarbu naudojimo atvejais, pavyzdžiui, išbandant paketą dėl nepertraukiamo integracijos serveryje.
versijos / versions.cfg:
& Nbsp; Versija prisegimą už bet kokius naudojamų Katilinės statyba paketus, kurie nėra dalis Zope priemonių rinkinį. Nuo tl.pkg versija, kuri yra reikalinga kuriant dokumentus yra segami į tą pačią versiją, sukurtą Pakuotės failus. Kai atnaujinate tl.pkg vėliau, ši versija prisegimą turi būti atnaujintas, kartu su visais failais, kurie pasikeitė pakuotės šabloną tarp versijų. Redaguoti šį failą pin apie bet kokius kiaušinius reikalaujama pagal savo paketą arba savo Katilinės statyba versijas.
versijos / ztk-versijos-X.Y.Z.cfg:
& Nbsp; fiksuoto spaudai Zope priemonių rinkinys, įtrauktas į mūsų versija pinnings. Laikydami vietinį kopiją tai leidžia kurti Katilinės statyba be prieigos prie tinklo. Negalima redaguoti šį failą.
Pagrindinė pakuotė dokumentacija
Yra tekstiniai failai, kurie turi būti rasti pakuotės aukščiausio lygio katalogą, yra standartines vienetų dokumentus, todėl tikimasi, toje vietoje ir pagal jų konkrečius pavadinimus, kurios turi būti prieinamos nepriklausomai nuo sfinkso. Šie failai turi galioti pertvarkytas tekstas, kaip jie yra tvarkomi Sfinksas statant visą dokumentaciją, išskyrus autorių teisių pranešimą ir licencijos tekstą, kuris yra įtrauktas pažodžiui.
README.txt: paketo tikslas, turinio ir naudojimo apžvalga, kuri bus dalis jo PyPI puslapyje ir dokumentacijos anketa rodyklės puslapį. Tai turėtų būti up-to-date su pakelio turinį visais laikais.
CHANGES.txt: Pakeitimai registruojami, kad reikia atnaujinti visus pakuotės pokyčius, kurie yra susiję su pakuotės vartotojams. Failo formatas yra suprantama zest.releaser ir dabartinės versijos jį (ty "tip" versija viešajame Mercurial saugykloje) bus atkreipė dėmesį į iš PyPI puslapyje ir užstatytos paketo dokumentuose.
ABOUT.txt: Kai apie pakuotės ir jos autorių, pavyzdžiui, pastarojo elektroninio pašto adresą ir pakuotės dokumentuose URL, PyPI puslapyje, emisijos tracker ir kodo, taip pat dabartinės žurnale patarimų. Manoma, kad dokumentai bus skelbiami tiek PyPI ir ; jums reikia įsitikinkite, kad naudoti teisingus pavestas savo projektą atitinkamas URL.
COPYRIGHT.txt teisės informacija apie paketas: autorių teisių turėtojo, įskaitant autorių metus ir kai apie naudojamos licencijos, kuri yra Zope viešosios licencijos, versija 2.1 pagal nutylėjimą patarimus. Redaguoti šį bent atnaujinti metus.
Licence.txt: oficialaus teksto naudojamos licencijos kopija. Negalima redaguoti šį, išskyrus pakeisti jį kitu licenciją.
Visa dokumentacija, pastatytas naudojant Sfinksas
dok: Viskas yra tai aktuali tik Sfinksas-generuoja dokumentus. Mes naudojame priesaga .txt Sphinx įvesties failai. Nors konvencijų numeris egzistuoti, doc kataloge turinį, nieko blogo atsitiks pakuotės, jei keisti tai laisvai poilsio; tiesiog įsitikinkite, kad jis galioja Sfinksas įėjimas.
doc / conf.py: Sfinksas konfigūraciją. Iš esmės visi konfigūracijos verčių laikytis konvencijų, todėl iš tl.pkg importuoti, todėl jūs turite išlaikyti importo ir iškviesti tl.pkg.sphinxconf nepažeistas. Jūs turėsite redaguoti šį failą, jei norite ką nors pakeisti metaduomenų ar dokumentus išvaizda tik už šį paketą. Atnaujinimai dėl Sfinksas-generuoja dokumentus konvencijų bus įsigijo atnaujinti tl.pkg.
doc / index.txt: priekinė puslapis dokumentus. Ji apima pakuotės apžvalga iš aukščiausio lygio readme.txt failą ir turinį nukreipta į visą dokumentaciją skyriuose lentelėje. Tai generuoja API dokumentaciją, kai meta informacijos apie pakuotės ir pakeitimai registruojami. Redaguoti šį failą, jei norite pridėti aukščiausio lygio sritis, pvz.
doc / narrative.txt:
& Nbsp; šaknis dokumentas pasakojimas paketo dokumentuose. Taip siekiama surinkti visus dok-testo failus, gyvena tarp Python modulių išeities tekstų medį. Jums reikia list failus pagal toctree direktyvos, jų dokumentų pavadinimai yra modelis -. (be .txt priesaga). Komentavo Išsiregistravimo failo pavyzdys sąrašas yra įtrauktas.
doc / api.txt: šaknis dokumentas sukurtas API dokumentacija. API dokumentais pusiau automatiškai, kad jūs turite išvardyti šio failo, pagal autosummary direktyvos, visi moduliai turi būti pagrįstos dokumentais, vyksta automatiškai nuo tada. Komentavo Išsiregistravimo pavyzdys modulis sąrašas yra įtrauktas.
doc / overview.txt:
& Nbsp; nebaigtas įtraukti aukščiausio lygio failą README.txt. Nereikia redaguoti šį failą.
doc / about.txt: Meta informacija apie pakuotės, derinant aukščiausio lygio failus ABOUT.txt, COPYRIGHT.txt ir licence.txt. Jums nereikės redaguoti šį failą.
doc / CHANGES.txt:
& Nbsp; nebaigtas įtraukti aukščiausio lygio failo CHANGES.txt. Nereikia redaguoti šį failą.
doc / requirements.pip:
& Nbsp; Python kiaušinių sąrašas (išskyrus patį Sfinksas), būtino norint sukurti dokumentus. Tai reiškė kurti dokumentus . Jūs turite būti į baltąjį sąrašą su jais, kad būtų galima naudoti konvencijas įgyvendina tl.pkg. Redaguoti šį failą, kai pakeisite savo Documentation paketo priklausomybių; Jūs negalite naudoti kiaušinių priedai čia.
kūrimas visus dokumentus
Sukurtas Katilinės statyba konfigūracija įdiegia scenarijų ne bin / doc, kad raginama Sfinksas statyti dokumentus. Norėdami paleisti šį scenarijų, jūsų dabartinis darbas katalogas turi būti paketas šaknis. Scenarijus bus įdėti pastatytas dokumentus į susikaupimo / doc / (santykinis pakuotės aukščiausio lygio kataloge). Praėjo bin / doc parinktys bus perduota į pagrindinės sfinksas-statyti komandą, tačiau pažymi, kad poziciniai argumentai neveiks.
Sphinx konfigūracijos verčių
Pagal nutylėjimą, Sphinx pratęsimų skaičius yra įjungtas, todėl jūs galbūt norėsite konfigūruoti juos be pagrindinių Sphinx kintamųjų:
- Sphinx.ext.autosummary
- Sphinx.ext.viewcode
- Sphinx.ext.inheritance_diagram
- Sphinxcontrib.cheeseshop
- Sphinxcontrib.issuetracker
Galite nepaisyti iš tl.pkg reikšmes tiesiog nustatant atitinkamus kintamuosius savo conf.py. Nuo tl.pkg.sphinxconf.set_defaults pritaikymo turi įvykti pabaigoje:
source_suffix = '.foo "
importo tl.pkg.sphinxconf
tl.pkg.sphinxconf.set_defaults ()
Priešingai, sphinxconf bando naudoti kintamuosius conf.py apskaičiuoti reikšmes. Jei šie kintamieji yra nurodyta, kad taip pat turi būti padaryta prieš set_defaults vadinamas. Šiuo metu, šie kintamieji yra pripažintas:
_year_started: Neprivaloma vertė metų projektas buvo pradėtas. Šis nutylėjimą einamųjų metų (tuo dokumentacijos pastato laiku), bet jei jis yra nurodyta ir skiriasi nuo einamųjų metų, ji yra naudojama statyti "autorių teisių pranešimą kaip" 2001-2012 Autorius ".
_flattr_url: Jei nenurodyta, tai yra laikoma, kad iš Flattr dalykas šiame projekte ir Flattr donorystės mygtukai bus rodomi ne iš meniu stulpelyje visą dokumentaciją viršuje URL. Norėdami pridėti Flattr mygtuką į PyPI puslapyje, odkomentować "paremti projektą" elementą ABOUT.txt ir užpildyti URL ten taip pat.
_issuetracker_offline:
& Nbsp; Jei nustatyta į tikrosios vertės, bitbucket integracija sphinxcontrib-issuetracker integracijos bus pakeista taip, kad jis bus ne bandyti pasiekti Serverio statant dokumentus ir Sphinx paleisti išlieka nepriklausoma nuo tinklo prieigos. (Integracija su kitais sekimo nebuvo pasirūpinta iki šiol.) Tai bus išjungti kai iš tracker integracijos funkciją, tačiau išlaikyti, pvz, kad issuetracker plėtinio gebėjimą atpažinti paprasto teksto išduoti numerius.
Galiausiai tl.pkg.sphinxconf modulis apibūdina funkciją, kad jūs galite skambinti užsiregistruoti juoktis modulius, jei dokumentacija turi būti pastatytas ant sistemos, kaip antai , kad negali įdiegti tam tikrą kodą (kaip modulių įgyvendinamos C):
tl.pkg.sphinxconf.register_mock_modules ("Kairas", "gobject", "gtk")

Reikalavimai :

• Python