tl.pkg

tl.pkg er en mal for en namespaced Python pakke med Sphinx docs.
Denne pakken genererer den grunnleggende fil og katalog layout av Python-pakker med Sphinx dokumentasjon og en utvikling buildout. Den består av to deler:
- En paste.script mal som skaper standardteksten for en Python pakke som bor i ett nivå av namespace, og
- En Python-modul som brukes til å konfigurere Sphinx, sammen med de nødvendige pakkeavhengigheter og noen theming.
Pakken fungerer med Python 2.6 og 2.7.
Bruk
For å gjøre paster mal, installerer tl.pkg hvor paster kan finne den. Deretter kjører paster:
& Nbsp;. Paster skape --template tl-pkg
Dette vil generere standardteksten for et egg distribusjon, komplett med zc.buildout konfigurasjon, skjelettet av Sphinx pakke dokumentasjon, og en Mercurial depot initialisert. Den buildout konfigurasjonen er rettet mot utvikling, så den vil installere en testrunner på bin / test og en dokumentasjon byggmester på bin / doc.
Noen variabler vil bli bedt for, blant dem en ett-linje beskrivelse og noen stikkord for pakken.
Tilpasning
Tre flere variabler som paster ber deg for er vant til å tilpasse pakken skjelettet det vil generere. Disse variablene kan ha standardverdiene som blir lest fra en fil med navnet $ HOME / .tl-pkg.cfg hvis den finnes. Filen må følge ini-fil syntaks som forstås av Pythons ConfigParser og inneholder en del (med et vilkårlig navn så langt) som definerer noen av følgende variabler:
forfatter: Ditt fulle navn. Dette vil vises i pakken metadata og dokumentasjon samt i opphavsretts meldinger om eventuelle Python filer generert.
forfatter-e-post: Din e-post adresse. Dette vises både i pakken metadata og dokumentasjon.
bitbucket-navn: Din bitbucket brukernavn. Dette brukes til å konstruere de ulike nettadresser som tilhører prosjektet. I dag, er forutsetningen at prosjektet vert på og eventuelle nettadresser i pakken metadata og dokumentasjon peker på aktuelle sider av at bitbucket prosjektet.
Innholdet Pakke
Dette er for å forklare hensikten med de genererte filer og kataloger, sammen med råd om hvilke filer som skal redigere når. Mange filer trenger ikke å bli redigert i det hele tatt.
Python distribusjon
setup.py: Pakken definisjon og metadata. Oppdatere denne filen minst når pakken versjonsnummer, avhengigheter, inngangspunkter endres.
: Kildekoden tre av pakken. Ikke endre navne pakkens __init__.py fil for at ikke andre pakker i samme navnerom ikke kan importeres.
Mercurial repository
.hg: Den Mercurial depot er allerede initialisert når pakken har blitt opprettet. De genererte filene ikke har blitt begått ennå.
.hg / hgrc: Repository konfigurasjon som peker til den fremtidige nettadressen til pakken i noen Mercurial hosting, hvis noen. Det setter også din hg brukernavn.
.hgignore: Filer og kataloger å bli ignorert av Mercurial. Dette omfatter lokal konfigurasjon og ting som forventes generert av buildout, bygger dokumentasjon eller pakke utgivelser. Den omfatter ikke filer generert av Python (for eksempel * .pyc), distribuere (* .egg-info), eller andre mer generelle verktøy som redaktør, som ikke er spesifikke for dette prosjektet. Slike mønstre bør være på standard Mercurial ignorere listen.
Utvikling buildout
bootstrap.py: Oppretter bin / buildout script. Kjør dette med den samme Python tolk som buildout bør bruke. Du trenger ikke å stadig endre denne filen.
buildout.cfg: En arbeidsgruppe buildout konfigurasjon som skaper en test løper og en dokumentasjon byggmester for pakken. Selve pakken inngår som en utvikle egg og buildout er konfigurert til å bruke bare låste versjoner av noen andre pakker. Redigere denne og konfigurere pakken offisielle utvikling buildout men sette lokale tilpasninger i local.cfg. Versjon byrdene gå i versjoner / versions.cfg mens denne filen versjoner delen skal bare angre byrdene av pakker som er erklært utvikle egg til denne samme fil buildout delen.
local.cfg: Lokale tilpasninger av buildout konfigurasjon som er av ingen interesse for andre utviklere. Dette blir ignorert av Mercurial. Hvis du endrer denne filen, kjører bin / buildout -c local.cfg fra da av. Selv om dette kan høres tungvint i starten, holder den ikke-lokale konfigurasjon i buildout.cfg og under versjonskontroll er viktig for brukstilfeller som teste pakken på en kontinuerlig-integreringsserver.
versjoner / versions.cfg:
& Nbsp; versjon låsing for alle pakker som brukes av buildout som ikke er en del av Zope verktøykasse. Versjonen av tl.pkg som er nødvendig for å bygge dokumentasjonen er festet til den samme versjonen som skapte pakkefiler. Når du oppgraderer tl.pkg senere, denne versjonen låsing behov for å bli oppdatert sammen med noen filer som er endret i pakken malen mellom versjonene. Rediger denne filen til pin versjonene av noen egg som kreves av pakken din eller din buildout.
versjoner / ztk-versjoner-X.Y.Z.cfg:
& Nbsp; En fast utgivelsen av Zope toolkit, inkludert i våre versjon byrdene. Holde en lokal kopi av dette gjør bygge buildout uten nettverkstilgang. Ikke rediger denne filen.
Generelt pakke dokumentasjon
Det finnes en rekke av tekstfiler som finnes i pakken sin toppkatalog som inneholder standard deler av dokumentasjonen og forventes derfor på det stedet og under deres spesielle navn, og som må være tilgjengelig uavhengig av Sphinx. Disse filene må være gyldig restrukturert tekst som de blir behandlet av Sphinx ved bygging av full dokumentasjon, med unntak av opphavsrett og lisens tekst som er inkludert ordrett.
README.txt: En oversikt over pakkenes formål, innhold og bruk som vil være en del av sin PyPI side og av dokumentasjonen indeks side. Dette bør holdes up-to-date med innholdet i pakken til alle tider.
CHANGES.txt: Endringsloggen som må oppdateres med eventuelle endringer i den pakken som er relevante for brukerne av pakken. Filens format blir forstått av zest.releaser og den nåværende versjonen av det (dvs. "tips" versjon i offentlig Mercurial repository) vil bli henvist til fra PyPI siden og pakken dokumentasjon bygget.
ABOUT.txt: Noen tips om pakken og dens forfattere, som sistnevnte e-postadresse og nettadressene til dokumentasjon pakkens, PyPI side, saksporeren og kildekode samt gjeldende loggen. Det antas at dokumentasjonen vil bli publisert både på PyPI og på ; du bør sørge for å bruke de riktige respektive URL-er tildelt prosjektet.
COPYRIGHT.txt: Copyright informasjon for pakken: opphavs inkludert opphavsretts år og noen råd om lisensen brukes, som er den Zope offentlig lisens, versjon 2.1 som standard. Redigere dette i det minste å oppdatere årene.
LICENSE.txt: En kopi av den offisielle lisensteksten brukes. Ikke rediger dette bortsett fra å bytte det for en annen lisens.
Full dokumentasjon, bygget ved hjelp av Sphinx
doc: Alt som er bare relevant for Sphinx generert dokumentasjon. Vi bruker suffikset .txt for Sphinx innspill filer. Mens en rekke konvensjoner finnes for innholdet i doc, vil ingenting vondt skje med resten av pakken hvis du endrer det fritt; bare sørg for at det fortsatt er gyldig Sphinx inngang.
doc / conf.py: Sphinx konfigurasjon. I utgangspunktet alle konfigurasjonsverdiene følge konvensjonene og er derfor importert fra tl.pkg, så du må holde import og påkalling av tl.pkg.sphinxconf intakt. Du må redigere denne filen hvis du ønsker å endre noe ved metadata eller utseendet av dokumentasjonen bare for denne pakken. Oppdateringer til konvensjonene for Sphinx generert dokumentasjon vil bli kjøpt ved å oppgradere tl.pkg.
doc / index.txt: Forsiden av dokumentasjonen. Det inkluderer oversikt pakken fra øverste nivå README.txt fil og en innholdsfortegnelse som peker til de delene av full dokumentasjon. Disse inkluderer generert API dokumentasjon, noen meta-informasjon om pakken og endringsloggen. Rediger denne filen hvis du ønsker å legge til toppnivå seksjoner, for eksempel.
doc / narrative.txt:
& Nbsp; Roten dokument av dokumentasjonen narrative pakken. Dette er ment å samle noen doc-testfiler som ligger blant de Python-moduler i kildetreet. Du trenger å liste opp filene under toctree direktivet deres dokumentnavnene være av mønsteret -. (uten .txt endelse). En kommen ut fila for eksempel oppføring er inkludert.
doc / api.txt: Roten dokument av den genererte API dokumentasjon. API er dokumentert semi-automatisk i det du har å liste i denne filen, under autosummary direktivet alle modulene skal dokumenteres, noe som skjer automatisk fra da av. En kommen-out eksempel modul oppføringen er inkludert.
doc / overview.txt:
& Nbsp; En spire til å inkludere toppnivåfilen README.txt. Ingen grunn til å redigere denne filen.
doc / about.txt: Meta informasjon om pakken, som kombinerer topp filer ABOUT.txt, COPYRIGHT.txt, og License.txt. Du trenger ikke å redigere denne filen.
doc / changes.txt:
& Nbsp; En spire til å inkludere toppnivå fil CHANGES.txt. Ingen grunn til å redigere denne filen.
doc / requirements.pip:
& Nbsp; En oversikt over Python egg (annet enn Sphinx selv) som kreves for å bygge dokumentasjonen. Dette er ment for å bygge dokumentasjonen på . Du må være hvitelistet med dem for å kunne bruke de konvensjoner implementert av tl.pkg. Rediger denne filen når din dokumentasjon er pakkeavhengig endring; du kan ikke bruke egg statister her.
Bygge full dokumentasjon
Den genererte buildout konfigurasjon installerer et skript på bin / doc som kaller Sphinx å bygge dokumentasjonen. Hvis du vil kjøre dette skriptet, må din nåværende arbeidskatalog være pakkerota. Skriptet vil sette den inne dokumentasjon i build / doc / (i forhold til pakkens toppkatalog). Opsjoner sendes til bin / doc vil bli gitt videre til den underliggende sfinksen-build-kommandoen, men merk at posisjon argumenter ikke vil fungere.
Sphinx konfigurasjonsverdier
Som standard er en rekke Sphinx utvidelser aktivert, så vil du kanskje konfigurere disse i tillegg til kjerne Sphinx variabler:
- Sphinx.ext.autosummary
- Sphinx.ext.viewcode
- Sphinx.ext.inheritance_diagram
- Sphinxcontrib.cheeseshop
- Sphinxcontrib.issuetracker
Du kan overstyre standardinnstillingene fra tl.pkg ved å sette de respektive variablene i din conf.py. Påkalling av tl.pkg.sphinxconf.set_defaults må skje på slutten:
source_suffix = '.foo'
import tl.pkg.sphinxconf
tl.pkg.sphinxconf.set_defaults ()
Omvendt, sphinxconf prøver å bruke variabler fra conf.py å beregne verdier. Hvis disse variablene er spesifisert, som også må gjøres før set_defaults kalles. Foreløpig er følgende variabler kjennes:
_year_started: Valgfri verdi for året prosjektet ble startet. Dette er standardinneværende år (på tidspunktet for byggedokumentasjon), men hvis det er spesifisert og forskjellig fra inneværende år, den brukes til å konstruere en opphavsrett som "2001-2012 forfatter".
_flattr_url: Hvis spesifisert, dette antas å være nettadressen til en Flattr ting for dette prosjektet og Flattr donasjon knapper vises på toppen av menyen kolonne i full dokumentasjon. For å legge til en Flattr-knapp til PyPI siden, uncomment "Støtte prosjektet" element i ABOUT.txt og fyll inn URL der også.
_issuetracker_offline:
& Nbsp; Hvis satt til en sann verdi, bitbucket integrering av sphinxcontrib-Issuetracker integrering vil bli endret slik at det ikke vil prøve å få tilgang til serveren ved bygging av dokumentasjon og Sfinxen løp forblir uavhengig av nettverkstilgang. (Integrasjon med andre trackere har ikke blitt tatt vare på så langt.) Dette vil deaktivere noen funksjonalitet tracker integrering, men beholde, f.eks, den Issuetracker forlengelse evne til å gjenkjenne ren tekst emisjons tall.
Endelig tl.pkg.sphinxconf modulen definerer en funksjon som du kan ringe for å registrere mock moduler dersom dokumentasjonen skal bygges på et system som som ikke kan installere viss kode (som moduler implementert i C):
tl.pkg.sphinxconf.register_mock_modules ('cairo', 'gobject', 'gtk')

Krav :

• Python