tl.pkg

tl.pkg adalah template untuk paket Python namespace dengan Sphinx docs.
Paket ini menghasilkan file dan direktori tata letak dasar paket Python dengan dokumentasi Sphinx dan buildout pembangunan. Ini terdiri dari dua bagian:
- Sebuah paste.script template yang menciptakan boilerplate untuk paket Python yang hidup di satu tingkat dari namespace, dan
- Modul Python yang digunakan untuk mengkonfigurasi Sphinx, bersama dengan dependensi paket yang diperlukan dan beberapa theming.
Paket ini bekerja dengan Python 2.6 dan 2.7.
Penggunaan
Untuk membuat template Paster tersedia, pasang tl.pkg mana Paster dapat menemukannya. Kemudian jalankan Paster:
& Nbsp;. Paster membuat --template tl-pkg
Ini akan menghasilkan boilerplate untuk distribusi telur, lengkap dengan konfigurasi zc.buildout, kerangka Sphinx dokumentasi paket, dan repositori Mercurial dijalankan. Konfigurasi buildout ditargetkan pada pengembangan, sehingga akan menginstal testrunner di bin / test dan pembangun dokumentasi di bin / doc.
Beberapa variabel akan diminta untuk, di antaranya deskripsi satu baris dan beberapa kata kunci untuk paket.
Personalisasi
Tiga variabel lagi yang Paster meminta Anda untuk digunakan untuk personalisasi paket kerangka itu akan menghasilkan. Variabel-variabel ini mungkin memiliki nilai default yang dibaca dari sebuah file bernama $ HOME / .tl-pkg.cfg jika ada. File perlu mengikuti sintaks Suami-berkas sebagaimana yang dipahami oleh Python ConfigParser dan mengandung satu bagian (dengan nama yang sewenang-wenang sejauh ini) yang mendefinisikan salah satu dari variabel-variabel berikut:
Penulis: Nama lengkap Anda. Hal ini akan muncul dalam metadata paket dan dokumentasi serta dalam pemberitahuan hak cipta dari file Python yang dihasilkan.
Penulis-email: Alamat e-mail Anda. Hal ini muncul baik dalam metadata paket dan dokumentasi.
bitbucket-nama: bitbucket nama pengguna Anda. Ini digunakan untuk membangun berbagai URL milik proyek. Saat ini, asumsi adalah bahwa proyek-host di dan setiap URL dalam paket metadata dan dokumentasi titik yang sesuai halaman proyek bitbucket.
Isi Paket
Hal ini menjelaskan tujuan dari file yang dihasilkan dan direktori, bersama dengan saran tentang file mana yang mengedit saat. Banyak file tidak perlu diedit sama sekali.
Distribusi Python
setup.py: Definisi paket dan metadata. Memperbarui file ini setidaknya setiap kali nomor versi paket tersebut, dependensi, titik masuk berubah.
: Pohon kode sumber dari paket. Jangan memodifikasi file __init__.py paket namespace ini supaya paket lain dalam namespace yang sama tidak dapat diimpor.
Repositori Mercurial
.hg: Repositori Mercurial sudah dijalankan ketika paket telah dibuat. File yang dihasilkan belum dilakukan belum.
.hg / hgrc: Konfigurasi Repositori yang menunjuk ke URL masa depan paket di beberapa hosting Mercurial, jika ada. Hal ini juga menetapkan nama pengguna hg Anda.
.hgignore: Berkas dan direktori untuk diabaikan oleh Mercurial. Ini termasuk konfigurasi lokal dan hal-hal yang diharapkan akan dihasilkan oleh buildout, dokumentasi membangun atau rilis paket. Ini tidak termasuk file yang dihasilkan oleh Python (seperti * Pyc), mendistribusikan (* .egg-info), atau alat yang lebih umum lainnya seperti editor, yang tidak spesifik untuk proyek ini. Pola tersebut harus di default Mercurial daftar abaikan.
Pengembangan buildout
bootstrap.py: Membuat script bin / buildout. Jalankan ini dengan interpreter Python yang sama yang buildout harus menggunakan. Tidak perlu pernah mengedit file ini.
buildout.cfg: Sebuah konfigurasi buildout kerja yang menciptakan seorang pelari tes dan pembangun dokumentasi untuk paket. Paket itu sendiri termasuk sebagai mengembangkan telur dan buildout dikonfigurasi untuk menggunakan versi hanya disematkan dari paket lain. Menyunting ini untuk mengkonfigurasi pengembangan buildout resmi paket tetapi menempatkan penyesuaian lokal local.cfg. Pinnings Versi masuk versi / versions.cfg sementara bagian versi file ini hanya harus membatalkan pinnings paket yang dinyatakan mengembangkan telur dengan bagian buildout file yang sama ini.
local.cfg: penyesuaian lokal dari konfigurasi buildout yang tidak menarik bagi pengembang lain. Hal ini diabaikan oleh Mercurial. Jika Anda mengubah file ini, jalankan bin / buildout local.cfg -c sejak saat itu. Meskipun hal ini mungkin terdengar rumit pada awalnya, menjaga konfigurasi non-lokal dalam buildout.cfg dan di bawah kontrol versi penting bagi kasus penggunaan seperti menguji paket pada server terus-integrasi.
versi / versions.cfg:
& Nbsp; Versi menjepit untuk setiap paket yang digunakan oleh buildout yang bukan bagian dari toolkit Zope. Versi tl.pkg yang dibutuhkan untuk membangun dokumentasi yang disematkan ke versi yang sama yang menciptakan file-file paket. Ketika melakukan upgrade tl.pkg kemudian, versi ini menyematkan kebutuhan yang akan diperbarui bersama dengan file yang telah berubah dalam paket template yang antara versi. Edit file ini untuk pin versi telur dibutuhkan oleh paket atau buildout Anda.
versi / ztk-versi X.Y.Z.cfg:
& Nbsp; Sebuah rilis tetap toolkit Zope, termasuk dalam pinnings versi kita. Menjaga salinan lokal ini memungkinkan membangun buildout tanpa akses jaringan. Jangan mengedit file ini.
Dokumentasi paket Umum
Ada beberapa file text yang akan ditemukan di direktori tingkat atas paket yang berisi potongan standar dokumentasi dan karena itu diharapkan di tempat itu dan di bawah nama khusus mereka, dan yang perlu independen diakses dari Sphinx. File-file ini harus berupa teks direstrukturisasi berlaku sebagai mereka sedang diproses oleh Sphinx ketika membangun dokumentasi lengkap, kecuali untuk pemberitahuan dan izin hak cipta teks yang termasuk verbatim.
README.txt: Sebuah gambaran dari paket tujuan, isi dan penggunaan yang akan menjadi bagian dari halaman PyPI dan halaman index dokumentasi itu. Hal ini harus terus up-to-date dengan isi kemasan setiap saat.
CHANGES.txt: Log perubahan yang perlu diperbarui dengan perubahan pada paket yang relevan dengan pengguna dari paket. Format file dipahami oleh zest.releaser dan versi saat itu (yaitu "tip" versi dalam repositori Mercurial publik) akan menunjuk ke dari halaman PyPI dan dokumentasi paket dibangun.
ABOUT.txt: Beberapa petunjuk tentang paket dan penulisnya, seperti alamat e-mail yang terakhir dan URL dokumentasi paket tersebut, halaman PyPI, pelacak isu dan kode sumber serta log saat ini. Diasumsikan dokumentasi yang akan dipublikasikan baik di PyPI dan pada ; Anda harus memastikan untuk menggunakan URL masing-masing yang benar ditugaskan untuk proyek Anda.
COPYRIGHT.txt: Informasi Hak Cipta untuk paket: pemegang hak cipta termasuk tahun hak cipta dan beberapa saran tentang lisensi yang digunakan, yang merupakan lisensi publik Zope, versi 2.1 secara default. Mengedit ini setidaknya untuk memperbarui tahun.
License.txt: Salinan naskah resmi lisensi yang digunakan. Jangan menyunting ini kecuali untuk menukarnya dengan lisensi yang berbeda.
Dokumentasi lengkap, dibangun menggunakan Sphinx
doc: Segala sesuatu yang hanya relevan dengan dokumentasi Sphinx yang dihasilkan. Kami menggunakan txt akhiran untuk Sphinx file input. Sementara sejumlah konvensi ada untuk isi dari direktori doc, tidak ada hal buruk yang akan terjadi ke seluruh paket jika Anda memodifikasi secara bebas; pastikan tetap Sphinx masukan yang valid.
doc / conf.py: konfigurasi Sphinx. Pada dasarnya semua nilai konfigurasi mengikuti konvensi dan karena itu diimpor dari tl.pkg, sehingga Anda harus menjaga impor dan doa tl.pkg.sphinxconf utuh. Anda harus mengedit file ini jika Anda ingin mengubah sesuatu tentang metadata atau penampilan dokumentasi hanya untuk paket ini. Update dengan konvensi untuk dokumentasi Sphinx yang dihasilkan akan diperoleh dengan meningkatkan tl.pkg.
doc / index.txt: Halaman depan dokumentasi. Ini mencakup ikhtisar paket dari tingkat atas berkas README.txt dan daftar isi menunjuk ke bagian dari dokumentasi lengkap. Ini termasuk dihasilkan dokumentasi API, beberapa informasi meta tentang paket dan log perubahan. Mengedit file ini jika Anda ingin menambahkan bagian tingkat atas, misalnya.
doc / narrative.txt:
& Nbsp; Dokumen akar dokumentasi paket narasi. Hal ini dimaksudkan untuk mengumpulkan file doc-tes yang berada di antara modul Python di pohon sumber Anda. Anda perlu daftar file di bawah arahan toctree, nama dokumen mereka yang dari pola -. (tanpa akhiran .txt). Sebuah daftar file contoh komentar-out disertakan.
doc / api.txt: Dokumen akar dokumentasi API yang dihasilkan. API ini didokumentasikan semi-otomatis dalam bahwa Anda harus daftar dalam file ini, di bawah arahan Autosummary, semua modul yang akan didokumentasikan, yang terjadi secara otomatis sejak saat itu. Sebuah daftar contoh modul komentar-out disertakan.
doc / overview.txt:
& Nbsp; Sebuah rintisan untuk menyertakan file top-level README.txt. Tidak perlu untuk mengedit file ini.
doc / about.txt: Informasi Meta tentang paket, menggabungkan file top-level ABOUT.txt, COPYRIGHT.txt, dan license.txt. Anda tidak perlu mengedit file ini.
doc / changes.txt:
& Nbsp; Sebuah rintisan untuk memasukkan tingkat atas berkas CHANGES.txt. Tidak perlu untuk mengedit file ini.
doc / requirements.pip:
& Nbsp; Sebuah daftar telur Python (selain Sphinx sendiri) yang diperlukan untuk membangun dokumentasi. Hal ini dimaksudkan untuk membangun dokumentasi di . Anda akan perlu daftar putih dengan mereka agar dapat menggunakan konvensi dilaksanakan oleh tl.pkg. Mengedit file ini setiap kali paket dependensi dokumentasi Anda berubah; Anda tidak dapat menggunakan ekstra telur di sini.
Membangun dokumentasi lengkap
Konfigurasi buildout yang dihasilkan menginstal script di bin / doc yang memanggil Sphinx untuk membangun dokumentasi. Untuk menjalankan script ini, direktori kerja Anda saat ini harus menjadi akar paket. Script akan menempatkan dokumentasi dibangun ke build / doc / (relatif terhadap direktori tingkat atas paket tersebut). Pilihan diteruskan ke bin / doc akan diteruskan ke mendasari sphinx-build perintah, tetapi perhatikan bahwa argumen posisi tidak akan bekerja.
Nilai konfigurasi Sphinx
Secara default, sejumlah Sphinx ekstensi diaktifkan, sehingga Anda mungkin ingin mengkonfigurasi ini selain variabel inti Sphinx:
- Sphinx.ext.autosummary
- Sphinx.ext.viewcode
- Sphinx.ext.inheritance_diagram
- Sphinxcontrib.cheeseshop
- Sphinxcontrib.issuetracker
Anda dapat mengganti default dari tl.pkg dengan hanya menetapkan variabel masing-masing di conf.py. Anda Seruan tl.pkg.sphinxconf.set_defaults perlu terjadi di akhir:
source_suffix = '.foo'
impor tl.pkg.sphinxconf
tl.pkg.sphinxconf.set_defaults ()
Sebaliknya, sphinxconf mencoba untuk menggunakan variabel dari conf.py untuk menghitung nilai-nilai. Jika variabel-variabel ini ditentukan, yang juga harus dilakukan sebelum set_defaults disebut. Saat ini, variabel-variabel berikut diakui:
_year_started: nilai Opsional untuk tahun proyek ini dimulai. Ini default untuk tahun berjalan (pada saat bangunan dokumentasi), tetapi jika ditentukan dan berbeda dari tahun berjalan, digunakan untuk membangun pemberitahuan seperti "2001-2012 Author" hak cipta.
_flattr_url: Jika ditentukan, ini diasumsikan URL hal Flattr untuk proyek ini dan tombol donasi Flattr akan muncul di bagian atas kolom menu dokumentasi lengkap. Untuk menambahkan tombol Flattr ke halaman PyPI, tanda komentar pada "Mendukung proyek" item dalam ABOUT.txt dan isi URL di sana juga.
_issuetracker_offline:
& Nbsp; Jika diatur ke nilai yang benar, integrasi bitbucket integrasi sphinxcontrib-issuetracker akan dimodifikasi sehingga tidak akan mencoba untuk mengakses server ketika membangun dokumentasi dan jangka Sphinx tetap independen dari akses jaringan. (Integrasi dengan pelacak lainnya belum diurus sejauh.) Ini akan menonaktifkan beberapa fungsi integrasi tracker tapi mempertahankan, misalnya, kemampuan issuetracker ekstensi untuk mengenali nomor isu plain-text.
Akhirnya, modul tl.pkg.sphinxconf mendefinisikan fungsi yang mungkin Anda menelepon untuk mendaftarkan modul mengejek jika dokumentasi tersebut akan dibangun di atas sistem seperti yang tidak dapat menginstal kode tertentu (seperti modul diimplementasikan dalam C):
tl.pkg.sphinxconf.register_mock_modules ('Kairo', 'GObject', 'gtk')

Persyaratan :

• Python