tl.pkg

tl.pkg ay isang template para sa isang namespaced Python pakete gamit ang Sphinx doc.
Ang paketeng ito ay bumubuo ang pangunahing file at direktoryo ng layout ng Python pakete na may Sphinx dokumentasyon at pag-unlad buildout. Binubuo ito ng dalawang bahagi:
- Isang template paste.script na lumilikha ang boilerplate para sa isang Python package na naninirahan sa isang antas ng namespace, at
- Isang Python module na ginagamit upang i-configure ang Sphinx, kasama ang mga kinakailangang mga dependency package at ang ilan theming.
Package ng gumagana sa Python 2.6 at 2.7.
Paggamit
Upang gawing available ang template paster, i-install tl.pkg kung saan maaari itong mahanap paster. Pagkatapos tumakbo paster:
& Nbsp;. Paster lumikha --template tl-pkg
Ito ay bubuo ang boilerplate para sa isang pamamahagi itlog, kumpleto sa configuration zc.buildout, balangkas ng dokumentasyon package Sphinx, at paiba-iba ang imbakan initialised. Ang configuration ng buildout ay naka-target sa pag-unlad, kaya ay i-install ito sa isang testrunner sa bin / pagsubok at dokumentasyon tagabuo sa bin / doc.
Ang ilang mga variable ay prompt ka para sa, kasama ng mga ito ng isang linya para sa paglalarawan at ilang mga keyword para sa package.
Personalisation
Tatlong higit pang mga variable na humihiling sa iyo para sa paster ay ginagamit upang i-personalize ang package balangkas ito ay bubuo. Mga variable na ito ay maaaring may mga default na halaga na magbasa mula sa isang file na may pangalang $ HOME / .tl-pkg.cfg kung umiiral na ito. Kailangang sundin INI-file syntax bilang maunawaan ng Python na ConfigParser at naglalaman ng isang seksyon (na may isang arbitrary na pangalan sa ngayon) na tumutukoy sa alinman sa mga sumusunod na variable ang file:
may-akda: Ang iyong buong pangalan. Ito ay lilitaw sa package na metadata at dokumentasyon pati na rin sa mga abiso sa copyright ng anumang mga file Python nabuo.
may-akda-email: Ang iyong e-mail address. Ito ay lilitaw sa parehong package na metadata at dokumentasyon.
bitbucket-name: Ang iyong bitbucket user name. Ito ay ginagamit upang bumuo ng mga iba't ibang mga URL na kasali sa proyekto. Sa kasalukuyan, ang palagay ay na ang proyekto ay naka-host sa at anumang mga URL sa package na metadata at dokumentasyon punto upang ilaan pahina ng na proyekto bitbucket.
Mga nilalaman ng Package
Ito ay upang ipaliwanag ang layunin ng nabuong mga file at mga direktoryo, kasama ng payo sa kung aling mga file upang i-edit kapag. Maraming mga file ay hindi na kailangan upang ma-edit sa lahat.
Python pamamahagi
setup.py: ang package na kahulugan at metadata. I-update ang file na ito ng hindi bababa sa tuwing numero ng bersyon ng pakete, ang mga dependency, baguhin ang entry point.
: Ang source code puno ng package. Huwag baguhin __init__.py file sa namespace pakete ng baka iba pang mga pakete sa parehong namespace ay hindi maaaring ma-import.
Papalit-palit imbakan
.hg: Ang papalit-palit imbakan ay naka-initialised kapag ang package ay nagawa na. Ang nabuong file ay hindi nai pa ginawa.
.hg / hgrc: imbakan configuration na tumuturo sa hinaharap URL ng pakete sa ilang mga papalit-palit sa pagho-host, kung mayroon man. Nagtatakda din ito ng iyong hg user name.
.hgignore: Ang mga file at mga direktoryo upang babalewalain ng paiba-iba. Kabilang dito ang mga lokal na configuration at mga bagay-bagay na inaasahang mabubuo sa pamamagitan ng buildout, dokumentasyon build o ilalabas ng package. Hindi kabilang dito ang mga file na binuo ng Python (tulad ng * .pyc), ipamahagi (* .egg-info), o iba pang mga mas pangkalahatang mga tool tulad ng iyong editor, na hindi partikular sa proyektong ito. Ay dapat na sa iyong default na papalit-palit huwag pansinin ang listahan nasabing mga pattern.
Pagpapaunlad buildout
bootstrap.py: Lumilikha ang bin / buildout script. Patakbuhin ito gamit ang parehong Python interpreter na dapat gamitin buildout. Hindi mo na kailangang kailanman edit ang file na.
buildout.cfg: Ang isang nagtatrabaho configuration buildout na lumilikha ng isang pagsubok na runner at dokumentasyon tagabuo para sa package. Ang pakete mismo ay kasama bilang isang bumuo ng itlog at buildout ay naka-configure upang gamitin lamang ang naka-pin na bersyon ng anumang ibang pakete. I-edit ang i-configure ang opisyal na pag-unlad buildout ang package ngunit ilagay lokal customisations sa local.cfg. Pinnings Bersyon pumunta sa bersyon / versions.cfg habang seksyon bersyon ng file na ito ay dapat lamang i-undo pinnings ng mga package na ipinahayag bumuo ng mga itlog sa pamamagitan ng seksyon buildout ang parehong file.
local.cfg: Lokal na customisations ng configuration buildout na ng walang interes sa iba pang mga developer. Ito ay babalewalain ng paiba-iba. Kung babaguhin mo ang file na ito, magpatakbo bin / buildout -c local.cfg mula sa pagkatapos sa. Habang ito ay maaaring tunog mahirap sa una, nang pinapanatili ang di-lokal na configuration sa buildout.cfg at sa ilalim ng bersyon control ay mahalaga para sa paggamit kaso tulad ng pagsubok ng package sa isang server tuluy-tuloy na-pagsasama.
bersyon / versions.cfg:
& Nbsp; Bersyon pinning para sa anumang mga pakete na ginamit ng mga buildout na hindi bahagi ng Zope toolkit. Ang bersyon ng tl.pkg na kinakailangan para sa pagbuo ng dokumentasyon ay naka-pin sa parehong bersyon na nilikha ang pakete ng mga file. Kapag ang pag-upgrade tl.pkg sa ibang pagkakataon, ang bersyon na ito pinning mga pangangailangan upang ma-update kasama ang anumang mga file na nagbago sa template pakete sa pagitan ng mga bersyon. I-edit ang file na ito upang i-pin ang mga bersyon ng anumang mga itlog na iniaatas ng iyong package o ang iyong buildout.
bersyon / ztk-bersyon-X.Y.Z.cfg:
& Nbsp; Ang isang nakapirming release ng Zope toolkit, kasama sa aming bersyon pinnings. Pagpapanatiling isang lokal na kopya ng nagbibigay-daan sa pagbuo ng buildout walang pag-access sa network. Huwag i-edit ang file na ito.
Pangkalahatang dokumentasyon ng package
Mayroong isang bilang ng mga teksto ng mga file na makikita sa top-level na direktoryo ng mga pakete na naglalaman ng karaniwang mga piraso ng papeles at samakatuwid ay inaasahan sa lugar na iyon at sa ilalim ng kanilang partikular na pangalan, at na kailangan upang ma-access independiyenteng ng Sphinx. Kailangan upang maging wasto restructured teksto habang ang mga ito ay ipinoproseso sa pamamagitan ng Sphinx kapag pagbuo ng ganap na dokumentasyon, maliban sa ang abiso sa copyright at lisensya ng teksto na kasama verbatim mga file na ito.
README.txt: Isang pangkalahatang-ideya ng package ng layunin, nilalaman at paggamit na maging bahagi ng pahina nito PyPI at ng index ng pahina ng dokumentasyon ng. Ito ay dapat na napapanatiling napapanahon sa mga nilalaman ng pakete sa lahat ng oras.
CHANGES.txt: Ang pagbabago ng log na Kailangang ma-update sa anumang mga pagbabago sa pakete na may-katuturan sa mga gumagamit ng package. Ang format ng file ay maunawaan ng mga zest.releaser at ang kasalukuyang bersyon nito (ie ang bersyon "tip" sa mga pampublikong papalit-palit imbakan) ay itinuturo sa mula sa pahina ng PyPI at ang built dokumentasyon na package.
ABOUT.txt: Ang ilang mga payo tungkol sa mga pakete at may-akda nito, tulad ng e-mail address sa huli at ang mga URL ng mga papeles sa pakete, ang PyPI pahina, isyu tracker at ang source code pati na rin ang kasalukuyang pag-log. Ito ay ipinapalagay na ang papeles ay mai-publish ang kapwa PyPI at sa ; dapat mong tiyaking gamitin ang tamang mga kani-kanyang mga URL na itinalaga sa iyong proyekto.
COPYRIGHT.txt: Impormasyon sa Copyright para sa mga package: may-hawak ng copyright kabilang ang mga taon ng copyright at ang ilang mga payo tungkol sa lisensya na ginagamit, kung saan ay ang Zope pampublikong lisensya, bersyon 2.1 sa pamamagitan ng default. I-edit ang hindi bababa sa i-update ang taon.
LICENSE.txt: Ang isang kopya ng opisyal na teksto ng lisensya na ginagamit. Huwag i-edit ito maliban upang makipagpalitan ng mga ito para sa ibang lisensya.
Buong dokumentasyon, na binuo gamit ang Sphinx
doc: Lahat na lang may-katuturan sa mga Sphinx binuo ng dokumentasyon. Ginagamit namin ang suffix .txt para sa Sphinx input file. Habang ang isang bilang ng mga convention umiiral para sa mga nilalaman ng direktoryo doc, walang masamang mangyayari sa natitirang bahagi ng package na kung ito ay malayang baguhin; tiyakin lamang na ito ay mananatiling wastong Sphinx input.
doc / conf.py: configuration Sphinx. Talaga ang lahat ng mga halaga ng configuration sundin ang mga convention at samakatuwid ay nai-import mula tl.pkg, kaya dapat mong panatilihin ang pag-import at pananalangin ng tl.pkg.sphinxconf buo. Kailangan mong i-edit ang file na ito kung gusto mong baguhin ang isang bagay tungkol sa metadata o ang hitsura ng dokumentasyon para lamang sa ang paketeng ito. Update sa mga convention para sa Sphinx binuo ng dokumentasyon ay nakuha sa pamamagitan ng pag-upgrade tl.pkg.
doc / index.txt: ang front page ng dokumentasyon. Kasama dito ang package na pangkalahatang-ideya mula sa README.txt file nangungunang antas at isang talaan ng nilalaman na nagtuturo sa mga seksyon ng buong dokumentasyon. Kabilang dito ang mga nabuong babasahin ukol sa API, ang ilang mga meta impormasyon tungkol sa pakete at ang log ng pagbabago. I-edit ang file na ito kung gusto mong magdagdag ng mga seksyon sa nangungunang antas, halimbawa.
doc / narrative.txt:
& Nbsp; Ang ugat dokumento ng dokumentasyon salaysay na package. Ito ay inilaan upang mangolekta ng anumang mga file doc-test na naninirahan sa mga Python mga module sa iyong mapagkukunan tree. Kailangan mong ilista ang mga file sa ilalim ng toctree directive, ang kanilang mga pangalan dokumento pagiging ng pattern -. (nang walang .txt suffix). Ang isang Nagkomento-out listahan halimbawa file ay kasama.
doc / api.txt: Ang ugat ng dokumento ang nabuong babasahin ukol sa API. API ay dokumentado semi-awtomatikong sa na mayroon ka upang ilista sa file na ito, sa ilalim ng autosummary directive, ang lahat ng mga module na dokumentado, na awtomatikong mangyayari mula sa oras na iyon. Ang isang Nagkomento-out listahan ng halimbawa ng module ay kasama.
doc / overview.txt:
& Nbsp; Ang isang stub para isama ang mataas na antas na file README.txt. Hindi mo na kailangang i-edit ang file na ito.
doc / about.txt: Meta impormasyon tungkol sa pakete, na pinagsasama-sama ang mga file nangungunang antas ABOUT.txt, COPYRIGHT.txt, at LICENSE.txt. Hindi mo na kailangang i-edit ang file na ito.
doc / changes.txt:
& Nbsp; Ang isang stub upang isama ang file CHANGES.txt nangungunang antas. Hindi mo na kailangang i-edit ang file na ito.
doc / requirements.pip:
& Nbsp; Isang listahan ng Python itlog (bukod sa sarili nito Sphinx) na kinakailangan upang bumuo ng mga papeles. Ito ay sinadya para sa pagbuo ng mga papeles sa . Kakailanganin mong i-whitelist ang mga ito upang maging magagawang gamitin ang convention sa ipinatupad ng tl.pkg. I-edit ang file na ito sa tuwing baguhin ang dependency ng package ng iyong papeles ni; Hindi mo maaaring gamitin ang itlog extra dito.
Building ang buong dokumentasyon
Ang nabuong configuration buildout i-install ng isang script sa bin / doc na tawag Sphinx upang bumuo ng mga papeles. Upang patakbuhin ang script na ito, ang iyong kasalukuyang nagtatrabaho direktoryo ay dapat na ang package na root. Ang script ay ilagay ang built dokumentasyon sa build / doc / (kamag-anak sa pinakamataas na antas ng direktoryo ng package ni). Mga Pagpipilian ipapasa sa bin / doc ay pumasa sa sa napapailalim na utos sphinx-build, ngunit tandaan na ang posisyonal argumento ay hindi gagana.
Mga halaga ng Sphinx configuration
Sa pamamagitan ng default, ang isang bilang ng mga Sphinx extension ay pinagana, kaya maaaring gusto mong i-configure ang mga bilang karagdagan sa core Sphinx variable:
- Sphinx.ext.autosummary
- Sphinx.ext.viewcode
- Sphinx.ext.inheritance_diagram
- Sphinxcontrib.cheeseshop
- Sphinxcontrib.issuetracker
Maaari mong i-override ang mga default mula sa tl.pkg sa pamamagitan lamang ng pagtatakda ng kaukulang variable sa iyong conf.py. Ang pananalangin ng tl.pkg.sphinxconf.set_defaults kailangang mangyari sa dulo:
source_suffix = '.foo'
-import tl.pkg.sphinxconf
tl.pkg.sphinxconf.set_defaults ()
Sa kabaligtaran, sinusubukan sphinxconf upang gamitin ang mga variable mula sa conf.py upang makalkula ang halaga. Kung ang mga variable na ay tinukoy, na dapat ding gawin bago set_defaults ay tinatawag na. Sa kasalukuyan, ang mga sumusunod na mga variable ay kinikilala:
_year_started: Opsyonal na halaga para sa taon na ang proyekto ay nagsimula. Ito ang mga default sa kasalukuyang taon (sa panahon ng dokumentasyon gusali), ngunit kung ito ay tinukoy at naiiba sa kasalukuyang taon, ito ay ginagamit upang bumuo ng abiso sa copyright tulad ng "2001-2012 May-akda".
_flattr_url: Kung tinukoy, ito ay ipinapalagay na ang URL ng isang flattr bagay para sa proyekto at flattr pindutan ng donasyon ay lilitaw sa tuktok ng menu ng hanay ng buong dokumentasyon. Upang magdagdag ng isang pindutan flattr sa pahina PyPI, uncomment ang "Suporta ng proyektong" na item sa ABOUT.txt at punan ang URL rin doon.
_issuetracker_offline:
& Nbsp; Kung nakatakda sa isang tunay na halaga, ang pagsasama-sama ng bitbucket ng pagsasama sphinxcontrib-issuetracker ay binago upang hindi ito ay susubukan na i-access ang server kapag pagbuo ng papeles at ang Sphinx run nananatiling independiyenteng ng pag-access sa network. (Pagsasama sa iba pang mga trackers ay hindi pa kinuha pangangalaga ng sa ngayon.) Hindi nito papaganahin ang ilang mga pag-andar ng pagsasama tracker ngunit panatilihin, hal, kakayahan ng extension issuetracker upang makilala ang mga numero plain-text isyu.
Panghuli, ang module tl.pkg.sphinxconf tumutukoy sa isang function na maaari mong tawagan para magparehistro kunwaring module kung ang babasahin ay dapat na binuo sa isang sistema tulad ng na hindi maaaring i-install sa ilang mga code (tulad ng mga module ipinapatupad sa C):
tl.pkg.sphinxconf.register_mock_modules ('Cairo', 'gobject', 'GTK')

Mga Kinakailangan :

• Python