tl.pkg

tl.pkg este un șablon pentru un pachet Python namespaced cu documente Sphinx.
Acest pachet generează fișier și director structura de bază a pachetelor Python cu documentație Sfinxul și o buildout dezvoltare. Se compune din două părți:
- Un șablon paste.script care creează șabloane pentru un pachet de Python care trăiește într-una nivel de spațiu de nume, și
- Un modul Python, care este folosit pentru a configura Sfinxul, împreună cu dependențele de pachete necesare și unele temelor.
Pachetul funcționează cu Python 2.6 și 2.7.
Utilizare
Pentru a face modelul Paster este disponibilă, instalați tl.pkg unde Paster poate găsi. Apoi rulați Paster:
& Nbsp;. Paster crea --template tl-pkg
Acest lucru va genera șabloane pentru o distribuție ou, complet cu configurație zc.buildout, scheletul de documentare pachet Sfinxul, și un depozit Mercurial inițializate. Configurația buildout se adresează dezvoltare, asa ca va instala o testrunner la bin / încercare și un constructor de documentare la bin / doc.
Câteva variabile se va cere, printre care o descriere-o linie și câteva cuvinte cheie pentru pachetul.
Personalizare
Încă trei variabile care Paster te pentru cere sunt folosite pentru a personaliza scheletul pachet se va genera. Aceste variabile pot avea valori implicite care sunt citite dintr-un fișier numit $ HOME / .tl-pkg.cfg dacă există. Fișierul trebuie să urmeze sintaxa-ini fișier așa cum este înțeles de către ConfigParser Python și conține o secțiune (cu un nume arbitrar până acum), care definește oricare dintre următoarele variabile:
autor: Nume complet. Aceasta va apărea în metadatele și documentația pachet, precum și în anunțuri drepturile de autor ale fișierelor Python generate.
autor-mail: Adresa dvs. de e-mail. Acest lucru apare atât în ​​metadatele și documentația pachet.
BitBucket-name: Nume de utilizator BitBucket. Acesta este folosit pentru a construi diferite URL-urile care aparțin proiectului. În prezent, ipoteza este că proiectul este găzduit la și orice URL-uri din punctul de metadate și documentației unui pachet să-și însușească pagini ale acestui proiect BitBucket.
Conținutul Pachetul
Acest lucru este de a explica scopul fișierele și directoarele generate, impreuna cu sfaturi despre ce fișiere pentru a edita când. Multe fișiere nu va trebui să fie editat deloc.
Distribuție Python
setup.py: Definiția și metadate pachet. Actualizati acest fișier, cel puțin atunci când numărul de versiune a pachetului, dependențe, punctele de intrare schimba.
: codul sursă copac a pachetului. Nu modificați fișierul __init__.py pachetului spațiul de nume de nu cumva alte pachete din același spațiul de nume nu pot fi importate.
Depozit Mercurial
.hg: Depozitul Mercurial este deja inițializată în cazul în care pachetul a fost creat. Fișierele generate nu au fost angajate încă.
.hg / hgrc: configurație Repository care indică viitoarea URL-ul pachetului, în unele hosting Mercurial, dacă este cazul. Acesta stabilește, de asemenea, numele de utilizator hg.
.hgignore: fișiere și directoare a fi ignorat de Mercurial. Aceasta include configurație locală și chestii așteaptă să fie generate de buildout, documentație construiește sau versiuni pachet. Ea nu include fișierele generate de Python (cum ar fi * .pyc), distribui (* .egg-info), sau alte instrumente mai generale, cum ar fi editorul, care nu sunt specifice acestui proiect. Aceste modele ar trebui să fie pe implicită Mercurial lista de ignorare.
Dezvoltarea buildout
bootstrap.py: Creează scriptul bin / buildout. Rulați acest lucru cu aceeași interpretorul Python care buildout ar trebui să utilizeze. Nu este nevoie pentru a edita vreodată acest fișier.
buildout.cfg: O configurație buildout lucru care creează un alergător de testare și un constructor de documentare pentru pachetul. Pachetul în sine este inclus ca un ou se dezvolta și buildout este configurat să utilizeze versiuni numai fixate de alte pachete. Editați acest pentru a configura buildout oficială pentru dezvoltare pachetul, dar încearcă personalizări locale în local.cfg. Pinnings Versiunea merge în versiuni / versions.cfg în timp ce secțiunea versiunile acest fișier ar trebui să anula numai pinnings de pachete care sunt declarate dezvolta ouă pe secțiuni buildout aceeași fișier.
local.cfg: personalizări locale ale configurației buildout că nu sunt de interes pentru alti dezvoltatori. Acest lucru este ignorat de Mercurial. Dacă schimbați acest fișier, executați bin / buildout local.cfg Ci de atunci. În timp ce acest lucru poate suna greoaie la început, păstrând configurația de bază non-locale în buildout.cfg și sub controlul versiune este importantă pentru cazurile de utilizare, cum ar fi testarea pachetul pe un server continuă integrare.
Versiunile / versions.cfg:
& Nbsp; Versiunea fixare pentru ambalaje utilizate de către buildout care nu fac parte din setul de instrumente Zope. Versiunea de tl.pkg care este necesară pentru construirea documentația este fixat la aceeași versiune care a creat fișierele pachet. Când actualizati tl.pkg mai târziu, această versiune are nevoie fixarea să fie actualizate, împreună cu toate fișierele care au schimbat în șablonul pachet între versiunile. Editează acest fișier la pinul versiunile orice ouă cerute de pachetul sau buildout ta.
Versiuni / ZTK-versiuni-X.Y.Z.cfg:
& Nbsp; O versiune fix a setului de instrumente Zope, inclus în versiunea pinnings noastre. Păstrarea o copie locală a acestui permite construirea buildout fără acces la rețea. Nu editați acest fișier.
Documentație General pachet
Există o serie de fișiere text care urmează să fie găsite în directorul de nivel superior pachetului care conține piese standard de documentației și, prin urmare, sunt așteptate în acel loc și sub numele lor specifice, și care trebuie să fie independent accesibil de Sphinx. Aceste fișiere trebuie să fie restructurate textul valabil în care acestea sunt prelucrate de către Sfinx atunci când construirea documentația completă, cu excepția dreptul de autor și licență de bază textul care sunt incluse textual.
README.txt: O privire de ansamblu de scopul, conținutul și utilizarea pachetului care va fi parte din pagină PyPI și a indicelui pagina documentației de. Acest lucru ar trebui să fie ținut la curent cu conținutul pachetului în orice moment.
CHANGES.txt: Jurnalul schimbare care trebuie să fie la curent cu orice modificare a pachetului care sunt relevante pentru utilizatorii pachetului. Formatul fișierului este înțeleasă de către zest.releaser și versiunea curentă a acesteia (de exemplu, versiunea "vârful" în magazia publice Mercurial) va fi arătat la de la pagina PyPI și documentația pachetului construit.
ABOUT.txt: Câteva indicii cu privire la pachetul și autorii săi, cum ar fi adresa de e-mail a acesteia și adresele URL de documentare pachetului, pagina PyPI, problema Tracker și codul sursă, precum și jurnalul curent. Se presupune că documentația va fi fi publicate atât la PyPI și la ; trebuie să vă asigurați de a utiliza URL-urile respective corecte alocate pentru proiectul dumneavoastra.
COPYRIGHT.txt: informații de autor pentru pachetul: deținătorul drepturilor de autor, inclusiv drepturile de autor și anii câteva sfaturi despre licența utilizat, care este licența publică Zope, versiunea 2.1 în mod implicit. Editați acest lucru cel puțin pentru a actualiza ani.
License.txt: O copie a textului oficial al licenței utilizat. Nu editați această decât să-l schimb pentru o licență diferit.
Documentație completă, construit folosind Sphinx
doc: Tot ceea ce este relevant numai la documentația Sphinx-a generat. Noi folosim .txt sufix pentru fișiere de intrare Sphinx. În timp ce un număr de convenții exista pentru conținutul directorului doc, nimic rău nu se va întâmpla cu restul pachetului dacă îl modificați în mod liber; doar asigurați-vă că rămâne intrare Sphinx valabil.
doc / conf.py: configurare Sfinxul. Practic toate valorile de configurare urmează convențiile și, prin urmare, sunt importate din tl.pkg, așa că trebuie să păstreze importul și invocarea tl.pkg.sphinxconf intact. Va trebui să editați acest fișier dacă doriți să schimbați ceva despre metadatele sau aspectul documentației doar pentru acest pachet. Actualizări la convențiile de documentare Sphinx-generat va fi achiziționate prin modernizarea tl.pkg.
doc / index.txt: prima pagină a documentației. Acesta include prezentarea generală pachet de fișier readme.txt de nivel superior și o cuprins indică spre secțiunile din documentația completă. Acestea includ documentația API a generat, unele informații despre meta pachet și jurnalul schimbare. Editează acest fișier dacă doriți să adăugați secțiuni de nivel superior, de exemplu.
doc / narrative.txt:
& Nbsp; Documentul rădăcină de documentația pachetului narativ. Acest lucru este destinat pentru a colecta orice fișiere doc-test care se află între module Python din arborele sursă. Ai nevoie pentru a lista fisierele temeiul directivei toctree, numele lor fiind documente de model -. (fără sufixul .txt). O listă exemplu de fișier comentat-out este inclus.
doc / api.txt: Documentul rădăcină a documentației API generat. API este documentată semi-automat că va trebui să înscrie în acest dosar, în temeiul directivei autosummary, toate modulele care urmează să fie documentate, care se întâmplă în mod automat de atunci. O listă exemplu modul comentate-out este inclus.
doc / overview.txt:
& Nbsp; un ciot pentru a include fișierul de nivel superior README.txt. Nu este nevoie pentru a edita acest fișier.
doc / about.txt: informații Meta despre pachetul, combinând fișierele de nivel superior ABOUT.txt, COPYRIGHT.txt, și license.txt. Tu nu va trebui să editați acest fișier.
doc / changes.txt:
& Nbsp; un ciot pentru a include CHANGES.txt fișier de nivel superior. Nu este nevoie pentru a edita acest fișier.
doc / requirements.pip:
& Nbsp; O lista cu ouă Python (altele decât Sfinxul sine) necesare pentru a construi documentația. Acest lucru este menit pentru construirea documentația la . Veți avea nevoie să fie pe lista albă cu ei, pentru a putea folosi convențiile implementate de tl.pkg. Editează acest fișier de fiecare dată când dependențele pachet de documente tău schimba; nu puteți utiliza figuranti ou aici.
Construirea documentația completă
Configurația buildout generat instalează un script la bin / doc care solicită Sfinx pentru a construi documentația. Pentru a rula acest script, directorul de lucru curent trebuie să fie rădăcina pachet. Scriptul va pune documentația construit în a construi / doc / (relativ la directorul de nivel superior pachetului). Opțiuni trecut la bin / doc va fi trecut pe la care stau la baza comenzii sfinx-build, dar rețineți că argumentele de poziție nu va funcționa.
Valorile de configurare Sphinx
În mod implicit, un număr de extensii Sphinx este activat, așa că poate doriți să configurați acestora în plus față de bază variabilele Sphinx:
- Sphinx.ext.autosummary
- Sphinx.ext.viewcode
- Sphinx.ext.inheritance_diagram
- Sphinxcontrib.cheeseshop
- Sphinxcontrib.issuetracker
Puteți înlocui valorile implicite din tl.pkg prin simpla stabilirea variabilele respective în conf.py. ta Invocarea de tl.pkg.sphinxconf.set_defaults trebuie să se întâmple la sfârșitul:
source_suffix = '.foo'
tl.pkg.sphinxconf import
tl.pkg.sphinxconf.set_defaults ()
În schimb, sphinxconf încearcă să utilizeze variabile de la conf.py pentru a calcula valorile. În cazul în care sunt specificate aceste variabile, care trebuie să fie, de asemenea, făcut înainte set_defaults se numește. În prezent, următoarele variabile sunt recunoscute:
_year_started: Valoarea opțional pentru anul proiectul a fost demarat. Aceasta implicit anul curent (în momentul de construcție documentare), dar în cazul în care este specificat și diferit de anul curent, este folosit pentru a construi un anunț de copyright ca "2001-2012 Autor".
_flattr_url: Daca este specificat, acest lucru se presupune a fi URL-ul unui lucru Flattr pentru acest proiect și butoane de donare Flattr va apărea în partea de sus a coloanei meniu a documentației complete. Pentru a adăuga un buton Flattr la pagina PyPI, decomentați "Sprijin proiectul" element în ABOUT.txt și completați URL-ul acolo, de asemenea.
_issuetracker_offline:
& Nbsp; Dacă este setat la o valoare adevărată, integrarea BitBucket integrării sphinxcontrib-issuetracker va fi modificată astfel încât să nu va încerca să acceseze Server atunci când construirea documentației și pe termen Sfinxul rămâne independent de acces la rețea. (Integrarea cu alte trackere nu a fost luată de îngrijire de până acum.) Aceasta va dezactiva putea funcționa integrării tracker dar păstrează, de exemplu, capacitatea de extinderea issuetracker de a recunoaște emite numere plain-text.
În cele din urmă, modulul tl.pkg.sphinxconf definește o funcție care s-ar putea apela la înregistra module false dacă documentația va fi construit pe un sistem, cum ar fi care nu se poate instala anumit cod (cum ar fi modulele implementat în C):
tl.pkg.sphinxconf.register_mock_modules ("Cairo", "gobject", "gtk ')

Cerințe :

• Python