tl.pkg

tl.pkg on mallina namespaced Python paketti Sphinx docs.
Tämä paketti luo perus- tiedostojen ja hakemistojen ulkoasu Python paketteja Sphinx asiakirjat ja kehityksen verkon rakentaminen. Se koostuu kahdesta osasta:
- Paste.script mallin, joka luo boilerplate varten Python paketti, joka asuu yhdessä tason nimiavaruus, ja
- Python-moduuli, jota käytetään määrittää Sphinx yhdessä pakettien riippuvuuksia ja joitakin teemoja.
Paketti toimii Python 2.6 ja 2.7.
Käyttö
Jotta saumaustelan mallin mahdollista, asenna tl.pkg jossa paster löytää sen. Sitten ajelu paster:
& Nbsp; paster luoda --template tl-pkt .
Tuloksiin boilerplate munaa jakelua, jossa zc.buildout kokoonpano, luuranko sfinksi paketti asiakirjoja, ja Mercurial arkiston alustetaan. Verkon rakentaminen kokoonpano on suunnattu kehittämiseen, joten se asentuu testrunner klo bin / testi ja asiakirjat rakentaja bin / doc.
Muutama muuttujia kysytään, heidän joukossaan yhden rivin kuvaus ja joitakin avainsanoja paketti.
Muokkaus
Kolme enemmän muuttujia, paster kysyy käytetään muokata paketin luuranko se tuottaa. Nämä muuttujat voivat olla oletusarvot, jotka luetaan tiedosto nimeltä $ HOME / .tl-pkg.cfg jos se on olemassa. Tiedosto on seurattava ini-tiedoston syntaksin ymmärtää Pythonin ConfigParser ja sisältävät yhden osan (jossa mielivaltainen nimi tähän asti), joka määrittelee jokin seuraavista muuttujista:
Kirjoittaja: Koko nimesi. Tämä näkyy paketin metatiedot ja asiakirjat sekä tekijänoikeustiedot tahansa Python tiedostoja syntyy.
kirjailija-email: Your e-mail osoite. Tämä näkyy sekä paketin metatiedot ja asiakirjat.
bitbucket-nimi: Oma bitbucket käyttäjätunnus. Tätä käytetään rakentaa eri URL-osoitteita kuuluvat projektiin. Tällä hetkellä oletus on, että hanke isännöi ja kaikki URL-paketin metatiedot ja asiakirjat pisteen asianmukaisille sivuille että bitbucket hanke.
Pakkauksen sisältö
Tämä on selittää tarkoituksen syntyy tiedostojen ja hakemistojen sekä neuvoja, mitkä tiedostot muokata milloin. Monet tiedostoja ei tarvitse muokata lainkaan.
Python jakelu
setup.py: paketti määritelmä ja metatiedot. Päivitä tämä tiedosto ainakin aina paketin versionumeron, riippuvuudet, rajanylityspaikoilla muuttua.
: lähdekoodi puu paketti. Älä muuta nimiavaruuden paketin __init__.py tiedosto ettei muita paketteja samaan nimiavaruuden ei voi tuoda.
Mercurial arkistosta
.hg: Mercurial arkistosta jo on alustettu, kun paketti on luotu. Luodut tiedostot eivät ole sidottuja vielä.
.hg / hgrc: Arkiston kokoonpano, joka osoittaa tulevaisuudessa URL paketin joissakin Mercurial hosting, jos mitään. Se myös asettaa oman Hg käyttäjätunnus.
.hgignore: Tiedostot ja hakemistot voidaan ohittaa Mercurial. Tämä sisältää paikallisia kokoonpano ja juttuja odotetaan tuottaman verkon rakentaminen, dokumentointi rakentaa tai paketti tiedotteita. Se ei sisällä tiedostoja syntyy Python (kuten * .pyc), jaella (* .egg-info), tai muita yleisempiä työkaluja kuten editori, jotka eivät liity erityisesti tähän hankkeeseen. Tällaisia ​​malleja pitäisi löytyä oletuksena Mercurial estolistan.
Kehitys verkon rakentaminen
bootstrap.py: Luo bin / verkon rakentaminen script. Suorita samalla Python-tulkki, että verkon rakentaminen tulisi käyttää. Ei tarvitse koskaan muokata tätä tiedostoa.
buildout.cfg: työskentely verkon rakentaminen kokoonpano, joka luo testi runner ja asiakirjat rakentaja paketti. Pakkaukseen on sisällytetty kehittää muna ja verkon rakentaminen on määritetty käyttämään vain puristuksiin versioita muita paketteja. Muokkaa tätä määrittää paketin virallista kehitysapua verkon rakentaminen vaan laittaa paikalliset mukauttamistöistä vuonna local.cfg. Versio pinnings mennä versioissa / versions.cfg, kun tämä tiedoston versiot osassa olisi vain kumoa pinnings paketeista ilmoitetaan kehittää munia tämän saman tiedoston verkon rakentaminen osiosta.
local.cfg: Paikallinen räätälöinnit verkon rakentaminen kokoonpano, joka ei ole mitään kiinnostusta muille kehittäjille. Tämä on sivuutettu Mercurial. Jos muutat tiedoston, suorita bin / verkon rakentaminen -c local.cfg lähtien. Vaikka tämä saattaa kuulostaa hankala aluksi, pitää ei-paikallinen kokoonpano buildout.cfg ja versioidulle on tärkeää käyttää tapauksissa, kuten testaus paketin jatkuva-Integration Server.
versiot / versions.cfg:
& Nbsp; Version kiinnittämällä mistään pakettien käyttämä verkon rakentaminen, jotka eivät kuulu Zope työkalupakin. Versio tl.pkg joka tarvitaan rakennuksen asiakirjat on kiinnitetty samaan versioon, joka loi paketti tiedostoja. Kun päivität tl.pkg myöhemmin, tämä versio panevat tarpeen päivittää sekä mahdolliset muuttuneet tiedostot pakettiin mallin versioiden väliset. Muokkaa tätä tiedostoa pin versioita mitään munia vaatimat pakettisi tai verkon rakentaminen.
versiot / ztk-versiot-X.Y.Z.cfg:
& Nbsp; kiinteä vapautuminen Zope työkalupakin, mukana meidän versio pinnings. Keeping paikallinen kopio tämä mahdollistaa rakentaa verkon rakentaminen ilman verkkoyhteyksiä. Älä muokkaa tätä tiedostoa.
Yleinen paketti asiakirjat
On useita tekstitiedostoja löytyy paketin ylätason hakemistoon, jotka sisältävät standardi kappaletta asiakirjat ja siksi odotettavissa, että paikka ja niiden erityisesti nimiä, ja joiden on oltava saatavilla riippumaton Sphinx. Nämä tiedostot täytyy olla voimassa uudelleen tekstin niitä käsitellään Sfinksi rakennettaessa täydellinen dokumentaatio, lukuun ottamatta tekijänoikeus ja lisenssitekstiin jotka sisältyvät sanatarkasti.
README.txt: yleiskatsaus paketin tarkoitus, sisältö ja käyttö, joka on osa sen PyPI sivun ja dokumentaation indeksiin sivulla. Tämä olisi pidettävä ajan tasalla kanssa paketin sisältö aina.
CHANGES.txt: muutos loki, joka on päivitetty muutoksia paketti, jotka ovat merkityksellisiä käyttäjille paketin. Tiedoston formaatti ymmärtävät zest.releaser ja nykyisen version (eli "kärki" versio julkisella Mercurial arkistoon) tullaan huomautti alkaen PyPI sivulta ja rakennettu paketti asiakirjat.
ABOUT.txt: Jotkut osoittimet noin paketti ja sen tekijöistä, kuten jälkimmäisen sähköpostiosoite ja URL-paketin ohjeista, PyPI sivu, vikaseurantaohjelmasta ja lähdekoodia sekä nykyisen lokin. Oletuksena on, että asiakirjat tulee julkaista sekä PyPI ja ; sinun tulisi varmista, että käytät oikeaa URL-osoitetta määritetty projektin.
COPYRIGHT.txt: Tekijänoikeudet tiedot paketti: tekijänoikeuden haltijan lukien tekijänoikeudet vuotta ja joitakin neuvoja lisenssin käyttää, mikä on Zope Public License, versio 2.1 oletuksena. Muokkaa tätä ainakin päivittää vuotta.
License.txt: kopio virallisesta tekstistä lisenssin käyttää. Älä muokkaa tätä paitsi vaihtaa sen eri lisenssin.
Kaikki ohjeet, rakennettu käyttäen Sphinx
doc: Kaikki mikä on merkitystä vain Sphinx syntyvän dokumentaation. Käytämme pääte .txt Sphinx syötetiedostoista. Vaikka useat yleissopimukset olemassa sisällöstä doc hakemiston, ei mitään pahaa tapahtuu muualla paketin, jos muokkaat sitä vapaasti; vain varmista, että se on voimassa sfinksi tulo.
doc / conf.py: Sphinx kokoonpano. Periaatteessa kaikki määritysarvot seurata yleissopimukset ja siksi tuotu tl.pkg, joten sinun täytyy pitää tuonnin ja vetoaminen tl.pkg.sphinxconf ehjä. Sinun täytyy muokata tätä tiedostoa, jos haluat muuttaa jotain metatiedot tai ulkonäkö asiakirjat vain tämän paketin. Päivitykset yleissopimusten sfinksi syntyvän asiakirjat hankitaan päivittämällä tl.pkg.
doc / index.txt: etusivulla asiakirjat. Se sisältää paketin katsauksen huipputason README.txt tiedosto ja sisällysluettelon osoittaa osiin liittyen. Näitä ovat luotu API dokumentaatio, jotkut meta tietoa paketin ja muutos loki. Muokkaa tätä tiedostoa, jos haluat lisätä huipputason osissa, esimerkiksi.
doc / narrative.txt:
& Nbsp; root dokumentti kerronta paketti asiakirjat. Tämä on tarkoitus kerätä kaikki doc-testi tiedostoihin, jotka sijaitsevat joukossa Python moduulit lähde puu. Sinun täytyy luetella tiedostoja toctree direktiivin niiden asiakirjojen nimet on rakenteessa . - (ilman .txt pääte). Kommentoi-out esimerkiksi listan sisältyy.
doc / api.txt: root asiakirja syntyy API-dokumentaation. API on dokumentoitu puoliautomaattisesti, että sinulla on luetella tämän tiedoston, alle autosummary direktiivin kaikki moduulit dokumentoitava, joka tapahtuu automaattisesti sen jälkeen. Kommentoi-out esimerkiksi moduuli listalle on mukana.
doc / overview.txt:
& Nbsp; tynkä sisällyttää huipputason tiedosto README.txt. Ei tarvitse muokata tätä tiedostoa.
doc / about.txt: Meta tietoa paketin, jossa yhdistyvät huipputason tiedostoja ABOUT.txt, COPYRIGHT.txt ja license.txt. Sinun ei tarvitse muokata tätä tiedostoa.
doc / changes.txt:
& Nbsp; tynkä sisällyttää huipputason tiedosto CHANGES.txt. Ei tarvitse muokata tätä tiedostoa.
doc / requirements.pip:
& Nbsp; listaus Python munia (muut kuin sfinksi itse) tarvitse rakentaa asiakirjat. Tämä on tarkoitettu rakennuksen asiakirjojen . Sinun täytyy olla sallituiksi heidän kanssaan voidakseen käyttää yleissopimusten täytäntöön tl.pkg. Muokkaa tätä tiedostoa aina kun asiakirjat paketti riippuvuudet muuttaa; et voi käyttää muna extrat täällä.
rakentaminen täysi dokumentaatio
Syntyy verkon rakentaminen kokoonpanon asentaa käsikirjoituksen bin / doc joka kutsuu Sphinx rakentaa asiakirjat. Voit suorittaa tämän komentosarjan, teidän työhakemistosta oltava paketin juureen. Skripti laittaa rakennettu dokumentaatio build / doc / (suhteessa paketin ylätason hakemistoon). Valinnat välitetään bin / doc välitetään taustalla sfinksi-build-komento, mutta huomaa, että asentohuimaus perusteluja ei toimi.
sfinksi määritysarvot
Oletuksena useita Sfinksi laajennuksia on käytössä, joten sinun kannattaa määrittää nämä lisäksi ydin Sphinx muuttujat:
- Sphinx.ext.autosummary
- Sphinx.ext.viewcode
- Sphinx.ext.inheritance_diagram
- Sphinxcontrib.cheeseshop
- Sphinxcontrib.issuetracker
Voit ohittaa luottotappioita tl.pkg yksinkertaisesti asettamalla niiden muuttujien teidän conf.py. Vetoaminen tl.pkg.sphinxconf.set_defaults täytyy tapahtua lopussa:
source_suffix = '.foo'
tuonti tl.pkg.sphinxconf
tl.pkg.sphinxconf.set_defaults ()
Kääntäen, sphinxconf yrittää käyttää muuttujat conf.py laskea arvoja. Jos nämä muuttujat on määritelty, että on myös tehtävä ennen set_defaults kutsutaan. Tällä hetkellä seuraavat muuttujat kirjataan:
_year_started: Valinnainen arvo vuoden projekti aloitettiin. Tämä oletuksena kuluvan vuoden (aikaan asiakirjat rakennus), mutta jos se on määritetty ja eroaa kuluvan vuoden, sitä käytetään rakentaa tekijänoikeus kuten "2001-2012 Tekijä".
_flattr_url: Mikäli määritelty, tämä oletetaan olevan URL Flattr asia tähän projektiin ja Flattr lahjoitus ilmestyvät yläosassa valikon sarakkeen kaikki asiakirjat. Voit lisätä Flattr painiketta PyPI sivulle, kommentoinnin "Support projekti" kohteen ABOUT.txt ja täytä URL siellä.
_issuetracker_offline:
& Nbsp; Jos asetettu todellisen arvon, bitbucket integrointi sphinxcontrib-issuetracker integraatio muutetaan niin, että se ei yritä käyttää palvelin rakennettaessa asiakirjat ja sfinksi run on riippumaton pääsy verkkoon. (Integrointi muihin seurantoja ei ole huolehdittu toistaiseksi.) Tämä poistaa joitakin toimivuutta tracker integraation mutta säilyttää esim issuetracker laajennus kyky tunnistaa pelkkää tekstiä kysymys numeroita.
Lopuksi tl.pkg.sphinxconf moduuli määrittelee toiminto, voit soittaa rekisteröityä pilkata moduuleja, jos asiakirjat on rakennettu järjestelmä, kuten että ei voi asentaa tiettyjä koodia (kuten moduulit toteutetaan C):
tl.pkg.sphinxconf.register_mock_modules ("Kairo", "gobject ',' GTK)

Vaatimukset :

• Python