tl.pkg

tl.pkg er en skabelon til en namespaced Python-pakke med Sphinx docs.
Denne pakke genererer den grundlæggende fil og mappe layout af Python-pakker med Sphinx dokumentation og en udvikling udbygningen. Den består af to dele:
- En paste.script skabelon, der skaber standardtekst for en Python-pakke, der bor i et niveau af namespace, og
- En Python-modul, der bruges til at konfigurere Sphinx, sammen med de nødvendige afhængigheder og nogle temaer.
Pakken arbejder med Python 2.6 og 2.7.
Anvendelse
For at gøre det Paster skabelon, kan du installere tl.pkg hvor Paster kan finde den. Derefter køre Paster:
& Nbsp;. Paster skabe --template TL-pkg
Dette vil generere standardtekst for et æg distribution, komplet med zc.buildout konfiguration, skelettet af Sphinx pakke dokumentation, og en Mercurial depot initialiseres. Udbygningen konfigurationen er rettet mod udvikling, så det vil installere en testrunner på bin / test og en dokumentation bygmester på bin / doc.
Et par variabler vil blive bedt om, blandt dem en one-line beskrivelse og nogle nøgleord for pakken.
Tilpasning
Yderligere tre variabler, Paster beder dig om er vant til at tilpasse pakken skelet det vil generere. Disse variabler kan have standardværdier, der læses fra en fil med navnet $ HOME / .tl-pkg.cfg hvis den findes. Filen skal følge ini-fil syntaks som forstås af Pythons ConfigParser og indeholder et afsnit (med hidtil et vilkårligt navn), der definerer en af ​​følgende variabler:
Forfatter: Dit fulde navn. Dette vil blive vist i pakken metadata og dokumentation samt i meddelelserne om ophavsret eventuelle Python filer genereret.
forfatter-mail: Din e-mail-adresse. Dette synes både i pakken metadata og dokumentation.
bitbucket-navn: Din bitbucket brugernavn. Dette bruges til at konstruere de forskellige webadresser, der tilhører projektet. På nuværende tidspunkt er den antagelse er, at projektet er hosted på og eventuelle webadresser i pakken metadata og dokumentation point til passende sider af denne bitbucket projekt.
Pakkens indhold
Dette er for at forklare formålet med de genererede filer og mapper, sammen med rådgivning om hvilke filer der skal redigeres, når. Mange filer behøver ikke at redigeres overhovedet.
Python fordeling
setup.py: Pakken definition og metadata. Opdater denne fil mindst når pakkens versionsnummer, afhængigheder, indgange ændres.
: Kildekoden træ af pakken. Du må ikke ændre pakkens namespace __init__.py fil lest andre pakker i samme navnerum ikke kan importeres.
Mercurial repository
.hg: Den Mercurial repository i forvejen er initialiseret, når pakken er blevet oprettet. De genererede filer er ikke blevet begået endnu.
.hg / hgrc: Repository konfiguration, der peger på den kommende URL af pakken i nogle Mercurial hosting, hvis nogen. Den fastsætter også dit hg brugernavn.
.hgignore: Filer og mapper, der skal ignoreres af Mercurial. Dette omfatter lokal konfiguration og stuff forventes at blive genereret af udbygningen, dokumentation bygger eller pakke udgivelser. Det omfatter ikke filer genereret af Python (såsom * .pyc), distribuere (* .egg-info), eller andre mere generelle værktøjer som din editor, som ikke er specifikke for dette projekt. Sådanne mønstre skal være på din standard Mercurial ignoreringsliste.
Udvikling udbygningen
bootstrap.py: Opretter bin / udbygningen script. Kør dette med det samme Python fortolkeren at udbygningen skal bruge. Ingen grund til nogensinde at redigere denne fil.
buildout.cfg: En arbejdsgruppe udbygningsblok konfiguration, der skaber en test runner og en dokumentation bygherre for pakken. Pakken selv indgår som en udvikler æg og udbygningen er konfigureret til kun at bruge fastgjorte versioner af andre pakker. Rediger dette til at konfigurere pakken officielle udvikling udbygningen men sætte lokale tilpasninger i local.cfg. Version pinnings gå i versioner / versions.cfg mens denne fils versioner afsnit bør kun fortryde pinnings af pakker, der er anmeldt udvikler æg af denne samme fils udbygningsblok sektion.
local.cfg: Lokale tilpasninger af udbygningen konfiguration, der ikke er af interesse for andre udviklere. Dette er ved at blive ignoreret af Mercurial. Hvis du ændrer denne fil, køre bin / udbygningen -c local.cfg fra da af. Selvom det kan lyde besværligt i starten, holder den ikke-lokale konfiguration i buildout.cfg og under versionskontrol er vigtig for sager brug, såsom at teste pakken på en kontinuerlig integration server.
versioner / versions.cfg:
& Nbsp; Version pinning for alle pakker, der anvendes af udbygningen, som ikke er en del af Zope toolkit. Den version af tl.pkg som er nødvendig for at bygge dokumentation fastgjort til den samme version, der har oprettet pakken filer. Når du opgraderer tl.pkg senere, at denne version pinning behov blive opdateret sammen med nogen filer, der er ændret i pakken skabelon mellem versionerne. Rediger denne fil at pin versioner af nogen æg kræves af din pakke eller dit udbygningen.
versioner / ZTK-versioner-X.Y.Z.cfg:
& Nbsp; En fast frigivelse af Zope toolkit, der indgår i vores version pinnings. Holde en lokal kopi af dette gør det muligt at bygge udbygningen uden netadgang. Du må ikke redigere denne fil.
Generel pakke dokumentation
Der er en række tekstfiler, der findes i pakken top-niveau mappe, der indeholder standard stykker af dokumentation og forventes derfor på dette sted og under deres særlige navne, og som skal være tilgængelig uafhængig af Sphinx. Disse filer skal være gyldige omstruktureret tekst som de bliver behandlet af Sphinx, når bygningen den fulde dokumentation, bortset fra ophavsret og licens tekst, som er medtaget ordret.
README.txt: En oversigt over pakkens formål, indhold og brug, som bliver en del af sin PyPI side og af dokumentationen indeks side. Dette bør holdes up-to-date med pakkens indhold på alle tidspunkter.
CHANGES.txt: Ændringen log, der har behov for at blive opdateret med eventuelle ændringer i pakken, som er relevante for brugerne af emballagen. Filen format forstås af zest.releaser og den aktuelle version af det (dvs. "tip" version i den offentlige Mercurial repository) blive peget på fra PyPI side og den indbyggede pakke dokumentation.
ABOUT.txt: Nogle pointers om pakken og dens forfattere, såsom dennes e-mail-adresse og webadresser på pakkens dokumentation PyPI side, udstedelse tracker og kildekode samt den aktuelle log. Det antages, at dokumentationen bliver offentliggjort både på PyPI og ved ; bør du sørge for at bruge de rigtige respektive webadresser tildelt dit projekt.
COPYRIGHT.txt: Copyright information for pakken: indehaveren af ​​ophavsretten herunder ophavsret år og nogle råd om licensen anvendes, hvilket er den Zope Public License, version 2.1 som standard. Rediger denne mindste at opdatere år.
LICENSE.txt: En kopi af den officielle ordlyd af licensen anvendes. Du må ikke redigere denne undtagen at bytte den til en anden licens.
Fuld dokumentation, bygget ved hjælp Sphinx
doc: Alt, hvad der kun er relevant for Sphinx-genererede dokumentation. Vi bruger endelsen .txt for Sphinx input filer. Mens en række konventioner eksisterer for indholdet af doc mappe, vil intet ondt ske med resten af ​​pakken, hvis du redigerer den frit; bare sørg for at det fortsat er gyldigt Sphinx input.
doc / conf.py: Sphinx konfiguration. Dybest set alle konfigurationsværdierne følger konventioner og derfor importeres fra tl.pkg, så du skal holde import og påkaldelse af tl.pkg.sphinxconf intakt. Du bliver nødt til at redigere denne fil, hvis du ønsker at ændre noget ved den metadata eller udseendet af dokumentationen blot for denne pakke. Opdateringer til konventionerne for Sphinx-genereret dokumentation vil blive erhvervet ved at opgradere tl.pkg.
doc / index.txt: Forsiden af ​​dokumentationen. Det omfatter pakken oversigt fra det øverste niveau README.txt fil og en indholdsfortegnelse, der peger på de dele af den fulde dokumentation. Disse omfatter genereret API-dokumentation, nogle meta oplysninger om pakken og ændringen log. Rediger denne fil, hvis du ønsker at tilføje øverste niveau sektioner, f.eks.
doc / narrative.txt:
& Nbsp; Roden dokument narrative pakke dokumentation. Dette har til formål at indsamle eventuelle doc-test filer, der findes blandt de Python moduler i din kilde træ. Du er nødt til at vise en filerne i henhold til direktivet toctree, deres dokumentnavne er af mønstret -. (uden .txt endelse). En kommenteret ud eksempel fil notering er inkluderet.
doc / api.txt: Roden dokument af den genererede API-dokumentation. API er dokumenteret semi-automatisk i, at du nødt til at liste i denne fil, under autosummary direktivet, at alle modulerne dokumenteres, hvilket sker automatisk fra da af. En kommenteret ud eksempel modul notering er inkluderet.
doc / overview.txt:
& Nbsp; En stub at inkludere filen topniveau README.txt. Ingen grund til at redigere denne fil.
doc / about.txt: Meta oplysninger om pakken, der kombinerer top-niveau-filer i ABOUT.txt, COPYRIGHT.txt og LICENSE.TXT. Du behøver ikke at redigere denne fil.
doc / changes.txt:
& Nbsp; En stub til at omfatte øverste niveau fil CHANGES.txt. Ingen grund til at redigere denne fil.
doc / requirements.pip:
& Nbsp; En liste over Python æg (bortset Sphinx selv), der kræves for at opbygge dokumentationen. Det er beregnet til at bygge dokumentation . Du bliver nødt til at blive whitelisten med dem for at kunne bruge de konventioner, der gennemføres af tl.pkg. Rediger denne fil, når din dokumentation er pakkeafhængigheder ændres; du kan ikke bruge æg extras her.
Opbygning af fuld dokumentation
Den genererede udbygningsblok konfiguration installerer et script på bin / doc der kalder Sphinx at bygge dokumentationen. Hvis du vil køre dette script, skal din aktuelle arbejdsmappe være pakken rod. Scriptet vil sætte den indbyggede dokumentation til build / doc / (i forhold til pakkens øverste niveau mappe). Indstillinger sendes til bin / doc vil blive videregivet til den underliggende sfinks-build kommando, men bemærk, at positionelle argumenter ikke virker.
Sphinx konfigurationsværdier
Som standard er en række Sphinx extensions slået til, så du måske ønsker at konfigurere disse ud over de centrale Sphinx variable:
- Sphinx.ext.autosummary
- Sphinx.ext.viewcode
- Sphinx.ext.inheritance_diagram
- Sphinxcontrib.cheeseshop
- Sphinxcontrib.issuetracker
Du kan tilsidesætte standardindstillingerne fra tl.pkg ved blot at sætte de respektive variabler i din conf.py. Påberåbelsen af ​​tl.pkg.sphinxconf.set_defaults skal ske i slutningen:
source_suffix = '.foo'
import tl.pkg.sphinxconf
tl.pkg.sphinxconf.set_defaults ()
Omvendt forsøger sphinxconf at bruge variabler fra conf.py til at beregne værdier. Hvis disse variabler er angivet, at der også skal gøres, før set_defaults hedder. I øjeblikket er følgende variabler anerkendes:
_year_started: Valgfri værdi for året projektet blev påbegyndt. Dette er som standard det indeværende år (på tidspunktet for dokumentation bygning), men hvis det er angivet, og forskellig fra det indeværende år, det bruges til at konstruere en meddelelse om ophavsret som "2001-2012 Forfatter".
_flattr_url: Hvis angivet, dette antages at være webadressen på en Flattr ting for dette projekt og Flattr donation knapper vises øverst i menuen kolonne i fuld dokumentation. For at tilføje en Flattr knap til PyPI siden udkommenter på "Støt projektet" post i ABOUT.txt og udfylde URL der.
_issuetracker_offline:
& Nbsp; Hvis sat til en sand værdi, bitbucket integration af sphinxcontrib-issuetracker integration vil blive ændret, så det ikke vil forsøge at få adgang til server, når opbygningen af ​​dokumentationen og Sphinx løb forbliver uafhængig af netværksadgang. (Integration med andre trackere ikke er hidtil taget sig af.) Dette vil deaktivere nogle funktioner af tracker integration men bevarer fx den issuetracker udvidelsen evne til at genkende almindelig tekst udstede numre.
Endelig tl.pkg.sphinxconf modulet definerer en funktion, som du kan anmode om at registrere mock moduler, hvis dokumentationen skal bygges på et system som der ikke kan installere visse kode (ligesom moduler implementeret i C):
tl.pkg.sphinxconf.register_mock_modules ('cairo', 'GObject', 'gtk')

Krav :

• Python