tl.pkg

tl.pkg είναι ένα πρότυπο για ένα namespaced πακέτο Python με Σφίγγα docs.
Αυτό το πακέτο δημιουργεί το βασικό αρχείο και κατάλογο διάταξη της Python πακέτων με Σφίγγα τεκμηρίωση και ανάπτυξη buildout. Αποτελείται από δύο μέρη:
- Ένα πρότυπο paste.script που δημιουργεί το στερεότυπο για ένα πακέτο Python που ζει σε ένα επίπεδο ονομάτων, και
- Μια μονάδα Python που χρησιμοποιείται για να διαμορφώσει Σφίγγα, μαζί με τις απαραίτητες εξαρτήσεις πακέτο και κάποια θεματοποίηση.
Το πακέτο λειτουργεί με την Python 2.6 και 2.7.
Χρήση
Για να κάνετε το πρότυπο Παστέρ διαθέσιμη, εγκαταστήστε tl.pkg όπου Παστέρ μπορεί να το βρει. Στη συνέχεια, εκτελέστε Παστέρ:
& Nbsp?. Παστέρ δημιουργούν --template TL-pkg
Αυτό θα δημιουργήσει το στερεότυπο για την κατανομή των αυγών, με πλήρη διαμόρφωση zc.buildout, ο σκελετός της Σφίγγας τεκμηρίωση του πακέτου, και ένα Mercurial αποθετήριο αρχικοποιείται. Η διαμόρφωση buildout απευθύνεται σε εξέλιξη, γι 'αυτό θα εγκαταστήσει ένα testrunner στο bin / δοκιμή και έναν οικοδόμο τεκμηρίωση στη bin / doc.
Λίγα μεταβλητές θα ζητηθεί, μεταξύ των οποίων και μια περιγραφή της μίας γραμμής και ορισμένες λέξεις-κλειδιά για το πακέτο.
Εξατομίκευση
Τρεις περισσότερες μεταβλητές που κολλητής σας για ζητά χρησιμοποιούνται για να διαμορφώσετε το σκελετό πακέτο θα δημιουργήσει. Αυτές οι μεταβλητές μπορεί να έχουν προκαθορισμένες τιμές που διαβάζονται από ένα αρχείο με όνομα $ HOME / .tl-pkg.cfg αν υπάρχει. Το αρχείο πρέπει να ακολουθήσει σύνταξη ini αρχείο όπως γίνεται κατανοητή από ConfigParser Python και περιέχει ένα τμήμα (με ένα αυθαίρετο όνομα μέχρι στιγμής) που ορίζει οποιαδήποτε από τις ακόλουθες μεταβλητές:
Συγγραφέας: Το πλήρες όνομά σας. Αυτό θα εμφανιστεί στα μεταδεδομένα πακέτο και εγγράφων, καθώς και στις ειδοποιήσεις πνευματικής ιδιοκτησίας οποιωνδήποτε αρχείων Python που δημιουργούνται.
Συγγραφέας-διεύθυνση: Διεύθυνση e-mail σας. Αυτό φαίνεται τόσο στα μεταδεδομένα συσκευασία και την τεκμηρίωση.
bitbucket-όνομα: bitbucket όνομα χρήστη σας. Αυτό χρησιμοποιείται για την κατασκευή των διαφόρων URLs που ανήκουν στο σχέδιο. Επί του παρόντος, η υπόθεση είναι ότι το έργο φιλοξενείται στο και οποιεσδήποτε διευθύνσεις URL στα μεταδεδομένα πακέτο και τεκμηρίωσης σημείο να οικειοποιηθεί τις σελίδες του εν λόγω σχεδίου bitbucket.
Περιεχόμενα Πακέτο
Αυτό είναι να εξηγήσει τον σκοπό των παραγόμενων αρχείων και καταλόγων, μαζί με συμβουλές για ποια αρχεία να επεξεργαστείτε πότε. Πολλά αρχεία δεν θα πρέπει να επεξεργαστεί καθόλου.
Διανομής της Python
setup.py: Ο ορισμός του πακέτου και τα μεταδεδομένα. Ενημέρωση αυτό το αρχείο, τουλάχιστον κάθε φορά που ο αριθμός έκδοσης του πακέτου, εξαρτήσεις, τα σημεία εισόδου αλλάξει.
: Το δέντρο πηγαίου κώδικα του πακέτου. Μην τροποποιείτε το αρχείο __init__.py του πακέτου ονομάτων του μήπως άλλα πακέτα στο ίδιο πεδίο ονομάτων δεν μπορεί να εισαχθεί.
Mercurial αποθετήριο
.hg: Το Mercurial αποθετήριο ήδη τεθεί σε εκκίνηση όταν έχει δημιουργηθεί το πακέτο. Τα παραγόμενα αρχεία δεν έχουν δεσμευθεί ακόμη.
.hg / hgrc: Καταθετήριο ρύθμιση παραμέτρων που παραπέμπει στο μέλλον URL του πακέτου σε κάποια Mercurial φιλοξενία, αν υπάρχουν. Θέτει επίσης Hg όνομα χρήστη σας.
.hgignore: αρχεία και τους καταλόγους να αγνοούνται από το Mercurial. Αυτό περιλαμβάνει την τοπική διαμόρφωση και πράγματα που αναμένεται να προκύψουν από buildout, τεκμηρίωση χτίζει ή εκδόσεις του πακέτου. Δεν περιλαμβάνει αρχεία που δημιουργούνται από την Python (όπως * .pyc), τη διανομή (* .egg-info), ή άλλες γενικότερες εργαλεία όπως συντάκτη σας, η οποία δεν είναι ειδικά για το συγκεκριμένο έργο. Τέτοια σχέδια θα πρέπει να είναι στην προεπιλογή σας Mercurial λίστα αγνόησης.
Ανάπτυξη buildout
bootstrap.py: Δημιουργεί το σενάριο bin / buildout. Εκτελέστε αυτό με τον ίδιο διερμηνέα Python ότι buildout θα πρέπει να χρησιμοποιούν. Δεν χρειάζεται να επεξεργαστείτε ποτέ αυτό το αρχείο.
buildout.cfg: Μια λειτουργική διαμόρφωση buildout που δημιουργεί ένας δρομέας δοκιμής και έναν οικοδόμο τεκμηρίωσης για το πακέτο. Το ίδιο το πακέτο περιλαμβάνεται ως αναπτύξουν αυγό και buildout έχει ρυθμιστεί ώστε να χρησιμοποιεί μόνο καρφώθηκε εκδόσεις για τα άλλα πακέτα. Επεξεργαστείτε τη για να διαμορφώσετε την επίσημη buildout ανάπτυξη του πακέτου, αλλά θέτοντας τις τοπικές επικοινωνιακό local.cfg. Pinnings Έκδοση πάει σε εκδόσεις / versions.cfg ενώ το τμήμα εκδόσεις αυτού του αρχείου θα πρέπει να αναιρέσετε μόνο pinnings των πακέτων που έχουν δηλωθεί να αναπτύξουν τα αυγά από το τμήμα buildout Αυτό το ίδιο αρχείου.
local.cfg: Τοπική παραμετροποιήσεις της διαμόρφωσης buildout που δεν παρουσιάζουν κανένα ενδιαφέρον για άλλους προγραμματιστές. Αυτό αγνοείται από Mercurial. Εάν αλλάξετε αυτό το αρχείο, εκτελέστε bin / buildout -c local.cfg από τότε. Ενώ αυτό μπορεί να ακούγεται περίπλοκη στην αρχή, διατηρώντας το μη-τοπική διαμόρφωση στην buildout.cfg και υπό τον έλεγχο του έκδοση είναι σημαντική για περιπτώσεις χρήσης, όπως η δοκιμή του πακέτου σε ένα διακομιστή συνεχούς ολοκλήρωσης.
εκδόσεις / versions.cfg:
& Nbsp? Έκδοση καρφώνει για τυχόν πακέτα που χρησιμοποιούνται από την buildout που δεν αποτελούν μέρος του πακέτου εργαλείων Zope. Η έκδοση του tl.pkg που απαιτείται για την οικοδόμηση της τεκμηρίωσης είναι καρφωμένο στην ίδια έκδοση που δημιούργησε τα αρχεία του πακέτου. Κατά την αναβάθμιση tl.pkg αργότερα, αυτή η έκδοση καρφώνει πρέπει να επικαιροποιηθεί, μαζί με όλα τα αρχεία που έχουν αλλάξει στο πρότυπο πακέτο μεταξύ των εκδόσεων. Επεξεργασία του αρχείου με την ακίδα τις εκδόσεις για τα αυγά που απαιτούνται από το πακέτο σας ή buildout σας.
εκδόσεις / ZTK-εκδόσεις-X.Y.Z.cfg:
& Nbsp? Μια σταθερή απελευθέρωση των εργαλείων Zope, που περιλαμβάνονται στην έκδοση pinnings μας. Κρατώντας ένα τοπικό αντίγραφο αυτό επιτρέπει την κατασκευή του buildout χωρίς πρόσβαση στο δίκτυο. Μην επεξεργαστείτε αυτό το αρχείο.
Γενική τεκμηρίωση του πακέτου
Υπάρχουν μια σειρά από αρχεία κειμένου να βρεθεί στον κατάλογο ανώτατου επιπέδου του πακέτου που περιέχει τυποποιημένα κομμάτια της τεκμηρίωσης και συνεπώς αναμένεται ότι σε αυτή τη θέση και κάτω από συγκεκριμένες ονομασίες τους, και τα οποία πρέπει να είναι προσβάσιμη ανεξάρτητα της Σφίγγας. Τα αρχεία αυτά πρέπει να είναι έγκυρη αναδιάρθρωση του κειμένου, δεδομένου ότι αποτελούν αντικείμενο επεξεργασίας από Σφίγγα κατά την οικοδόμηση της πλήρους τεκμηρίωσης, εκτός από το δικαίωμα πνευματικής ιδιοκτησίας και την άδεια κείμενο που περιλαμβάνονται αυτολεξεί.
README.txt: Μια επισκόπηση του σκοπού, τα περιεχόμενα του πακέτου και χρήσης, τα οποία θα αποτελέσουν μέρος της σελίδας του PyPI και της σελίδας του δείκτη της τεκμηρίωσης του. Αυτό πρέπει να ληφθεί up-to-ημερομηνία με τα περιεχόμενα της συσκευασίας ανά πάσα στιγμή.
CHANGES.txt: Το ημερολόγιο αλλαγή που πρέπει να ενημερωθεί με τις τυχόν τροποποιήσεις του πακέτου που είναι σχετικές με τους χρήστες του πακέτου. Η μορφή του αρχείου είναι κατανοητή από zest.releaser και την τρέχουσα έκδοση του (δηλαδή την «άκρη» εκδοχή στο δημόσιο Mercurial αποθετήριο) θα επισημάνει από τη σελίδα PyPI και την ενσωματωμένη τεκμηρίωση του πακέτου.
ABOUT.txt: Μερικές υποδείξεις σχετικά με το πακέτο και τους συντάκτες του, όπως διεύθυνση e-mail του τελευταίου και τις διευθύνσεις URL της τεκμηρίωσης του πακέτου, PyPI σελίδα, το θέμα tracker και τον πηγαίο κώδικα, καθώς και το τρέχον ημερολόγιο. Υποτίθεται ότι η τεκμηρίωση θα πρέπει να δημοσιευθεί τόσο σε PyPI και σε ? θα πρέπει να βεβαιωθείτε ότι χρησιμοποιείτε τις σωστές αντίστοιχες διευθύνσεις URL που αποδίδεται στο έργο σας.
COPYRIGHT.txt: Οι πληροφορίες πνευματικών δικαιωμάτων για το πακέτο: κατόχου των πνευματικών δικαιωμάτων, συμπεριλαμβανομένων των δικαιωμάτων πνευματικής ιδιοκτησίας χρόνια και κάποιες συμβουλές σχετικά με την άδεια που χρησιμοποιείται, η οποία είναι η δημόσια άδεια Zope, έκδοση 2.1 από προεπιλογή. Επεξεργαστείτε αυτό τουλάχιστον να ενημερώσετε τα χρόνια.
LICENSE.txt: Ένα αντίγραφο του επίσημου κειμένου του πιστοποιητικού που χρησιμοποιείται. Μην επεξεργαστείτε αυτό εκτός από το να το ανταλλάξει για μια διαφορετική άδεια.
Πλήρης τεκμηρίωση, χτίστηκε χρησιμοποιώντας Σφίγγα
DOC: Ό, τι έχει σχέση μόνο με την Σφίγγα δημιουργείται τεκμηρίωση. Χρησιμοποιούμε το .txt κατάληξη για τα αρχεία εισόδου Σφίγγα. Ενώ ένας αριθμός των συμβάσεων που υπάρχουν για τα περιεχόμενα του καταλόγου doc, τίποτα κακό θα συμβεί με το υπόλοιπο του πακέτου αν το τροποποιήσετε ελεύθερα? απλά βεβαιωθείτε ότι παραμένει σε ισχύ εισόδου Σφίγγα.
doc / conf.py: διαμόρφωση Σφίγγα. Βασικά όλες οι τιμές διαμόρφωσης ακολουθούν συμβάσεις και ως εκ τούτου, τα εισαγόμενα από tl.pkg, έτσι θα πρέπει να κρατήσει την εισαγωγή και την επίκληση του tl.pkg.sphinxconf άθικτη. Θα πρέπει να επεξεργαστείτε αυτό το αρχείο, εάν θέλετε να αλλάξετε κάτι σχετικά με τα μεταδεδομένα ή την εμφάνιση της τεκμηρίωσης ακριβώς για αυτό το πακέτο. Ενημερώσεις για τις συμβάσεις για Σφίγγα δημιουργείται τεκμηρίωση θα αποκτηθεί από την αναβάθμιση tl.pkg.
doc / index.txt: Η πρώτη σελίδα της τεκμηρίωσης. Περιλαμβάνει την επισκόπηση πακέτο από το top-level αρχείο README.txt και έναν πίνακα περιεχομένων που δείχνουν προς τα τμήματα του πλήρους φακέλου. Αυτά περιλαμβάνουν δημιουργούνται τεκμηρίωση API, κάποια μετα-πληροφορίες σχετικά με το πακέτο και την αλλαγή καταγραφής. Επεξεργαστείτε το συγκεκριμένο αρχείο, εάν θέλετε να προσθέσετε ενότητες υψηλού επιπέδου, για παράδειγμα.
doc / narrative.txt:
& Nbsp? Το έγγραφο ρίζα της τεκμηρίωσης αφήγησης πακέτο. Αυτό έχει ως στόχο να συγκεντρώσει όλα τα αρχεία doc-τεστ που βρίσκονται μεταξύ των ενοτήτων Python στο δέντρο του πηγαίου σας. Θα πρέπει να εμφανιστούν τα αρχεία σύμφωνα με την οδηγία toctree, τα ονόματα τους έγγραφο είναι της μορφής -. (χωρίς την κατάληξη .txt). Ένα σχολίασε-out λίστα παράδειγμα αρχείο περιλαμβάνεται.
doc / api.txt: Το έγγραφο ρίζα της παραγόμενης API τεκμηρίωση. Το API είναι τεκμηριωμένη ημι-αυτόματα ότι θα πρέπει να συμπεριληφθεί στο παρόν αρχείο, κάτω από το autosummary οδηγία, όλες οι ενότητες που πρέπει να τεκμηριώνονται, πράγμα που συμβαίνει αυτόματα από τότε. Ένα σχολίασε-out λίστα παράδειγμα ενότητας συμπεριλαμβάνεται.
doc / overview.txt:
& Nbsp? Ένα στέλεχος να συμπεριλάβετε το αρχείο ανώτατου επιπέδου README.txt. Δεν χρειάζεται να επεξεργαστείτε αυτό το αρχείο.
doc / about.txt: Meta πληροφορίες σχετικά με το πακέτο, συνδυάζοντας τα αρχεία υψηλού επιπέδου ABOUT.txt, COPYRIGHT.txt, και LICENSE.txt. Δεν θα χρειαστεί να επεξεργαστείτε αυτό το αρχείο.
doc / changes.txt:
& Nbsp? Ένα στέλεχος να περιλαμβάνει το top-level αρχείο CHANGES.txt. Δεν χρειάζεται να επεξεργαστείτε αυτό το αρχείο.
doc / requirements.pip:
& Nbsp? Μια λίστα Python αυγά (εκτός από την ίδια τη Σφίγγα) που απαιτούνται για την κατασκευή του έγγραφα. Αυτό προορίζεται για την κατασκευή της τεκμηρίωσης σε . Θα πρέπει να λίστα επιτρεπόμενων μαζί τους, προκειμένου να είναι σε θέση να χρησιμοποιούν τις συμβάσεις που εφαρμόζονται από tl.pkg. Επεξεργαστείτε το συγκεκριμένο αρχείο κάθε φορά που εξαρτήσεις πακέτο τεκμηρίωσης σας αλλάξει? δεν μπορείτε να χρησιμοποιήσετε έξτρα αυγό εδώ.
Οικοδομώντας την πλήρη τεκμηρίωση
Το παραγόμενο διαμόρφωση buildout εγκαθιστά ένα σενάριο στο bin / doc που καλεί Σφίγγα για να χτίσει την τεκμηρίωση. Για να εκτελέσετε αυτό το σενάριο, τρέχοντα κατάλογο εργασίας σας πρέπει να είναι η ρίζα πακέτο. Το σενάριο θα θέσει το ενσωματωμένο τεκμηρίωση σε κατασκευή / doc / (σε σχέση με τον κατάλογο ανώτατου επιπέδου του πακέτου). Επιλογές που περνούν στο bin / doc θα μετακυλίεται στον υποκείμενο εντολή σφίγγα-κατασκευής, αλλά σημειώστε ότι τα επιχειρήματα της θέσης δεν θα λειτουργήσει.
Τιμές Σφίγγα διαμόρφωση
Από προεπιλογή, ο αριθμός των επεκτάσεων Σφίγγα είναι ενεργοποιημένα, οπότε ίσως να θέλετε να ρυθμίσετε τις παραμέτρους αυτές εκτός από τις μεταβλητές Σφίγγα πυρήνα:
- Sphinx.ext.autosummary
- Sphinx.ext.viewcode
- Sphinx.ext.inheritance_diagram
- Sphinxcontrib.cheeseshop
- Sphinxcontrib.issuetracker
Μπορείτε να παρακάμψετε τις προεπιλεγμένες τιμές από tl.pkg απλά τον καθορισμό των αντίστοιχων μεταβλητών σε conf.py. σας Η επίκληση του tl.pkg.sphinxconf.set_defaults πρέπει να συμβεί στο τέλος:
source_suffix = '.foo »
tl.pkg.sphinxconf εισαγωγής
tl.pkg.sphinxconf.set_defaults ()
Αντίθετα, sphinxconf προσπαθεί να χρησιμοποιήσει μεταβλητές από conf.py για τον υπολογισμό των τιμών. Εάν δεν έχουν καθοριστεί οι μεταβλητές, που πρέπει επίσης να γίνει πριν set_defaults ονομάζεται. Επί του παρόντος, οι ακόλουθες μεταβλητές αναγνωρίζονται:
_year_started: Προαιρετική αξία για το έτος που ξεκίνησε το έργο. Αυτό προεπιλογές για το τρέχον έτος (κατά το χρόνο του κτιρίου τεκμηρίωση), αλλά αν ορίζεται διαφορετικά και από το τρέχον έτος, χρησιμοποιείται για την κατασκευή ενός ειδοποίηση πνευματικών δικαιωμάτων, όπως "2001-2012 Συγγραφέας".
_flattr_url: Εάν οριστεί, υποτίθεται ότι είναι η διεύθυνση URL μιας Flattr πράγμα για το έργο αυτό και Flattr κουμπιά δωρεά θα εμφανιστεί στην κορυφή της στήλης μενού του πλήρους φακέλου. Για να προσθέσετε ένα κουμπί Flattr στη σελίδα PyPI, φύγετε το "υποστηρίξουν το έργο" στον ABOUT.txt και συμπληρώστε τη διεύθυνση URL και εκεί.
_issuetracker_offline:
& Nbsp? Αν οριστεί σε μια πραγματική αξία, η ενσωμάτωση bitbucket της ολοκλήρωσης sphinxcontrib-issuetracker θα τροποποιηθεί έτσι ώστε δεν θα προσπαθήσει να αποκτήσετε πρόσβαση στο διακομιστή κατά τη δημιουργία της τεκμηρίωσης και την πορεία Σφίγγα παραμένει ανεξάρτητη από την πρόσβαση στο δίκτυο. (Ενοποίηση με άλλα συστήματα παρακολούθησης δεν έχει ληφθεί μέριμνα μέχρι στιγμής.) Αυτό θα απενεργοποιήσει κάποια λειτουργικότητα της ολοκλήρωσης tracker αλλά διατηρούν, για παράδειγμα, η ικανότητα της επέκτασης issuetracker να αναγνωρίσει τους αριθμούς έκδοσης απλού κειμένου.
Τέλος, η μονάδα tl.pkg.sphinxconf ορίζει μια λειτουργία που μπορείτε να καλέσετε για να εγγραφείτε εικονικές μονάδες εάν η τεκμηρίωση θα πρέπει να βασίζεται σε ένα σύστημα όπως το που δεν μπορείτε να εγκαταστήσετε συγκεκριμένο κωδικό (όπως ενότητες εφαρμόζεται σε C):
tl.pkg.sphinxconf.register_mock_modules («Κάιρο», «GObject», «gtk")

Απαιτήσεις :

• Python