tl.pkg

tl.pkg är en mall för ett namnområde Python paket med Sphinx docs.
Detta paket genererar grundläggande fil och katalog layout Python-paket med Sphinx dokumentation och en utveckling utbyggnad. Den består av två delar:
- En paste.script mall som skapar standardtext för en Python-paket som lever i en nivå av namespace, och
- En Python-modul som används för att konfigurera Sphinx, tillsammans med de nödvändiga paketberoenden och vissa teman.
Paketet fungerar med Python 2.6 och 2.7.
Användning
För att göra det paster mall som finns, installera tl.pkg där paster kan hitta den. Sedan köra paster:
& Nbsp;. Paster skapa --template tl-pkg
Detta kommer att generera standardtext för ett ägg fördelning, komplett med zc.buildout konfiguration, skelettet av Sphinx paketet dokumentation och en Mercurial förvar initieras. Utbyggnaden konfigurationen riktar sig utvecklingen, så det kommer att installera ett testrunner på bin / test och dokumentationsbyggare på bin / dok.
Några variabler kommer att bli tillfrågad om, bland dem en enradig beskrivning och vissa sökord för paketet.
Anpassa
Ytterligare tre variabler som paster frågar efter används för att anpassa paketet skelettet det kommer att generera. Dessa variabler kan ha standardvärden som läses från en fil som heter $ HOME / .tl-pkg.cfg om den finns. Filen måste följa ini-fil syntax som förstås av Pythons ConfigParser och innehåller en sektion (med ett godtyckligt namn hittills) som definierar någon av följande variabler:
författare: Ditt fullständiga namn. Detta kommer att visas i paketet metadata och dokumentation samt i copyright av eventuella Python filer som genereras.
Författaren-post: Din e-postadress. Detta visas både i förpackningen metadata och dokumentation.
bitbucket-namn: Din bitbucket användarnamn. Detta används för att konstruera de olika webbadresser som hör till projektet. För närvarande är antagandet att projektet är värd på och eventuella webbadresser i paketet metadata och dokumentation punkten till lämpliga sidor av denna bitbucket projekt.
Paketets innehåll
Detta för att förklara syftet med de genererade filer och kataloger, tillsammans med råd om vilka filer att redigera när. Många filer behöver inte redigeras alls.
Python fördelning
setup.py: Paketet definitionen och metadata. Uppdatera den här filen minst när paketets versionsnummer, beroenden, startpunkter förändras.
: Käll kodträd av paketet. Ändra inte namn paketets __init__.py fil lest andra paket i samma namnrymd inte kan importeras.
Mercurial förvaret
.hg: Den Mercurial förvaret redan initieras när paketet har skapats. De genererade filerna har inte begått ännu.
.hg / hgrc: arkiv konfiguration som pekar på framtida URL av paketet i någon Mercurial hosting, om något. Den innehåller också ditt hg användarnamn.
.hgignore: Filer och kataloger som ska ignoreras av Mercurial. Detta inkluderar lokal konfiguration och grejer förväntas genereras av utbyggnad, bygger dokumentation eller paket utgåvor. Den omfattar inte filer som genereras av Python (t.ex. * .pyc), distribuera (* .egg-info), eller andra mer generella verktyg som din redaktör, som inte är specifika för detta projekt. Sådana mönster ska vara på din förvalda Mercurial ignorera listan.
Utveckling buildout
bootstrap.py: Skapar bin / utbyggnaden manus. Kör detta med samma Python tolken att utbyggnaden ska använda. Inget behov av att någonsin redigera filen.
buildout.cfg: En arbetsgrupp utbyggnads konfiguration som skapar en testlöpare och dokumentations byggare för paketet. Själva förpackningen ingår som en utvecklar ägg och utbyggnad är konfigurerad att använda endast nålas versioner av några andra paket. Redigera den och konfigurera paketet officiella utvecklings utbyggnad men satte lokala anpassningar i local.cfg. Version pinnings går i versioner / versions.cfg medan detta filens versioner avsnitt bör endast ångra pinnings av paket som deklareras utvecklar ägg från samma filens utbyggnadssektion.
local.cfg: Lokala anpassningar av utbyggnaden konfiguration som är av intresse för andra utvecklare. Detta ignoreras av Mercurial. Om du ändrar den här filen, kör bin / utbyggnad -c local.cfg därefter. Även om detta kanske låter besvärligt i början, att hålla den icke-lokala konfigurationen i buildout.cfg och under versionskontroll är viktigt för användningsfall, t.ex. testa paketet på en kontinuerlig-integreringsservern.
versioner / versions.cfg:
& Nbsp; Version pinning för de paket som används av utbyggnaden som inte ingår i Zope toolkit. Den version av tl.pkg som krävs för att bygga dokumentationen är låst till samma version som skapade paketfiler. Vid uppgradering tl.pkg senare, att denna version pinning behov uppdateras tillsammans med eventuella filer som har ändrats i paketet mallen mellan versionerna. Redigera denna fil till stift versionerna av några ägg som krävs av ditt paket eller ditt utbyggnaden.
versioner / ZTK-versioner-X.Y.Z.cfg:
& Nbsp; En fast utgåvan av Zope toolkit, som ingår i vår version pinnings. Att hålla en lokal kopia av detta tillåter bygga utbyggnaden utan accessnätet. Redigera inte den här filen.
Allmän paketdokumentation
Det finns ett antal textfiler som finns i paketet: s toppnivå katalog som innehåller standard bitar av dokumentation och väntas därför på den platsen och under deras särskilda namn, och som måste vara tillgängliga oberoende av Sphinx. Dessa filer måste vara giltigt omstrukturerade texten som de håller på att behandlas av Sphinx när man bygger den fullständiga dokumentationen, med undantag för upphovsrätts och licenstext som ingår ordagrant.
README.txt: En översikt över paketets syfte, innehåll och användning som kommer att vara en del av sin PyPI sida och dokumentation indexsida. Detta bör hållas up-to-date med förpackningens innehåll hela tiden.
CHANGES.txt: Förändringen loggen som behöver uppdateras med eventuella ändringar i paketet som är relevanta för användarna av paketet. Filen format förstås av zest.releaser och den nuvarande versionen av det (dvs "spets" version i den offentliga Mercurial förvaret) kommer att pekade på från PyPI sidan och den byggda paketet dokumentationen.
ABOUT.txt: Vissa pekare om paketet och dess författare, såsom den senares e-postadress och URL i paketet dokumentation, PyPI sida, fråga tracker och källkoden samt det aktuella loggen. Det förutsätts att dokumentation kommer att publiceras både på PyPI och vid ; bör du se till att använda rätt respektive webbadresser som tilldelats ditt projekt.
COPYRIGHT.txt: Copyright-information om paketet: upphovsrättsinnehavaren inklusive upphovsrätts åren och några råd om licensen används, vilket är Zope offentliga licensen, version 2.1 som standard. Redigera denna åtminstone att uppdatera åren.
LICENSE.TXT: En kopia av den officiella texten av licensen som används. Redigera inte detta förutom att byta ut det mot en annan licens.
Full dokumentation, byggd med Sphinx
doc: Allt som är endast relevant för Sphinx genererade dokumentation. Vi använder suffixet .txt för Sphinx indatafiler. Medan ett antal konventioner existerar för innehållet i katalogen doc, kommer inget dåligt att hända med resten av paketet om du ändrar den fritt; se bara till att det förblir giltigt Sphinx ingång.
doc / conf.py: Sphinx konfiguration. I princip alla konfigurationsvärdena följer konventioner och därför importeras från tl.pkg, så du måste hålla import och åkallan av tl.pkg.sphinxconf intakt. Du måste redigera den här filen om du vill ändra något om metadata eller utseendet på dokumentationen bara för detta paket. Uppdateringar till konventionerna för Sphinx-genererad dokumentation kommer att förvärvas genom att uppgradera tl.pkg.
doc / index.txt: Den första sidan av dokumentationen. Den innehåller paketet översikt från README.txt toppnivå och en innehållsförteckning som pekar på de avsnitt i den fullständiga dokumentationen. Dessa inkluderar genererade API-dokumentation, en del metainformation om paketet och ändringsloggen. Redigera denna fil om du vill lägga till toppnivå sektioner, till exempel.
doc / narrative.txt:
& Nbsp; Roten dokumentet i berättelsen paketet dokumentation. Detta är tänkt att samla in några doc-testfiler som bor bland Python moduler i källträdet. Du måste lista filerna enligt direktivet toctree, deras dokumentnamn är av mönstret -. (utan .txt suffix). En kommenterade ut exempelfil notering ingår.
doc / api.txt: Roten dokumentet från genererade API-dokumentation. API dokumenteras halvautomatiskt i att du måste lista i denna fil, under autosummary direktivet, för att alla moduler dokumenteras, vilket sker automatiskt därefter. En kommenterade-out exempel modul notering ingår.
doc / overview.txt:
& Nbsp; En påbörjad att inkludera toppnivå fil README.txt. Inget behov av att redigera filen.
doc / about.txt: Meta information om paketet, som kombinerar den översta nivån filer ABOUT.txt, COPYRIGHT.txt och LICENSE.TXT. Du kommer inte att behöva redigera filen.
doc / changes.txt:
& Nbsp; En påbörjad att inkludera toppnivå fil CHANGES.txt. Inget behov av att redigera filen.
doc / requirements.pip:
& Nbsp; En lista över Python ägg (annat än Sphinx själv) som krävs för att bygga dokumentationen. Detta är tänkt för att bygga dokumentation på . Du måste vara vitlistas med dem för att kunna använda de konventioner som genomförs av tl.pkg. Redigera denna fil när din dokumentation paketberoenden förändras; du kan inte använda ägg extramaterial här.
Bygga full dokumentation
Den genererade utbyggnad konfiguration installerar ett skript på bin / doc som kallar Sphinx att bygga dokumentationen. För att köra skriptet, måste din nuvarande arbetskatalog vara paketroten. Manuset kommer att sätta den inbyggda dokumentationen i build / doc / (i förhållande till paketets toppnivå katalog). Alternativ som skickas till bin / doc kommer att vidarebefordras till den underliggande sfinxen-build kommandot, men observera att positions argument inte kommer att fungera.
Sphinx konfigurationsvärden
Som standard är ett antal Sphinx förlängningar aktiverat, så du kanske vill ställa in detta i tillägg till de centrala Sphinx variablerna:
- Sphinx.ext.autosummary
- Sphinx.ext.viewcode
- Sphinx.ext.inheritance_diagram
- Sphinxcontrib.cheeseshop
- Sphinxcontrib.issuetracker
Du kan åsidosätta standardinställningarna från tl.pkg genom att helt enkelt ställa de respektive variablerna i ditt conf.py. Åkallan av tl.pkg.sphinxconf.set_defaults måste ske i slutet:
source_suffix = '.foo'
import tl.pkg.sphinxconf
tl.pkg.sphinxconf.set_defaults ()
Omvänt försöker sphinxconf att använda variabler från conf.py att beräkna värden. Om dessa variabler anges, som måste också göras innan set_defaults heter. För närvarande är följande variabler erkänd:
_year_started: Valfri värde för året projektet startades. Förval är innevarande år (vid tidpunkten för dokumentations byggnad), men om den är specificerad och skiljer sig från innevarande år, det används för att konstruera ett meddelande om upphovsrätt som "2001-2012 Författare".
_flattr_url: Om angivet, detta antas vara webbadressen till en Flattr sak för detta projekt och Flattr donationsknappar visas högst upp i menyn kolumnen i full dokumentation. För att lägga till en Flattr-knapp till PyPI sidan, avkommentera "stödja projektet" objektet i ABOUT.txt och fyll i URL där också.
_issuetracker_offline:
& Nbsp; Om satt till ett sant värde, det bitbucket integration av sphinxcontrib-issuetracker integration kommer att ändras så att den inte kommer att försöka komma åt server när man bygger dokumentationen och Sfinxen run förblir oberoende av nätverksåtkomst. (Integration med andra trackers inte har tagit hand om hittills.) Detta kommer att inaktivera vissa funktioner på tracker integration men behålla, t.ex. den issuetracker förlängning förmåga att känna igen vanlig text emissionsnummer.
Slutligen definierar tl.pkg.sphinxconf modulen en funktion som du kan ringa för att registrera håna moduler om dokumentationen ska byggas på ett system, såsom som inte kan installera viss kod (som moduler implementeras i C):
tl.pkg.sphinxconf.register_mock_modules ("cairo ',' gobject ',' gtk ')

Krav :

• Python