tl.pkg

tl.pkg Sfenks dokümanlar ile alanlı Python paketi için bir şablon olduğunu.
Bu paket Sfenks belgelerine ve geliştirme buildout Python paketleri temel dosya ve dizin düzenini oluşturur. Bu iki bölümden oluşur:
- Bir paste.script ad bir düzeyde yaşayan bir Python paketi için klişe oluşturur şablon, ve
- Gerekli paket bağımlılıkları ve bazı tema ile birlikte, Sfenks yapılandırmak için kullanılan bir Python modülü.
paket Python 2.6 ve 2.7 ile çalışır.
Kullanım
Paster nerede bulabilirim tl.pkg yüklemek, Paster şablonu kullanılabilir duruma getirmek için. Sonra Paster çalıştırın:
& Nbsp;. Paster --template tl-pk oluşturmak
Bu zc.buildout yapılandırması, Sfenks paket belgelerin iskelet ve başlatılır Mercurial depo ile tam bir yumurta dağıtımı için klişe, üretecektir. o bin / test bir testrunner ve bin / doc bir belge oluşturucu kuracak, böylece buildout yapılandırma, geliştirme hedeflenmektedir.
Birkaç değişkenler aralarında, bir tek satır açıklama ve paket için bazı anahtar kelimeler istenecektir.
Kişiselleştirme
Paster için sorar üç değişken de üretecektir paket iskeleti kişiselleştirmek için kullanılır. Bu değişkenler varsa adlı bir dosya $ HOME / .tl-pkg.cfg okunan varsayılan değerleri olabilir. Dosya Python'ın ConfigParser tarafından anlaşılmış ve (şimdiye kadar keyfi bir isimle) bir bölüm ihtiva aşağıdaki değişkenlerden herhangi tanımlar ini dosyası sözdizimi takip etmek gerekiyor:
Yazar: Tam adınız. Bu paket metadata ve dokümantasyon yanı sıra oluşturulan herhangi bir Python dosyalarının telif hakkı bildirimleri görünecektir.
Yazar-e-: E-posta adresiniz. Bu paket metadata ve belgelerde hem de görünür.
bitbucket-Adınız: bitbucket kullanıcı adı. Bu projeye ait çeşitli URL'leri oluşturmak için kullanılır. Şu anda, varsayım projesi barındırılan ve paket metadata ve dokümantasyon noktasında herhangi URL'ler o bitbucket projesinin sayfalarını mülk olmasıdır.
Paket içeriği
Bu zaman düzenlemek için hangi dosyaların tavsiye ile birlikte, oluşturulan dosya ve dizinleri amacını açıklamak için. Birçok dosyaları tüm düzenlenebilir gerek olmayacak.
Python dağıtımı
setup.py: paket tanımı ve metadata. Paketin sürüm numarası, bağımlılıkları, giriş noktaları değiştirmek, en azından zaman bu dosyayı güncelleyin.
: Paketin kaynak kodu ağacı. Aynı ad diğer paketler ithal edilemez diye ad paketin __init__.py dosyasını değişiklik yapmayın.
Mercurial depo
.hg: paket oluşturulduğunda Mercurial depo zaten başlatılır. oluşturulan dosyaları henüz taahhüt edilmemiştir.
.hg / hgrc: Depo yapılandırma varsa, bazı Mercurial barındırma paketinin gelecekteki URL'ye işaret. Aynı zamanda hg kullanıcı adını ayarlar.
.hgignore: Dosyalar ve dizinleri Mercurial tarafından göz ardı edilecek. Bu buildout, dokümantasyon oluşturur veya paket bültenleri tarafından oluşturulan beklenen yerel yapılandırmasını ve malzeme içerir. Bu (* .egg-bilgi) dağıtmak, ya da bu projeye özgü olmayan tüm editörü gibi diğer daha genel araçlar, (örneğin .pyc * gibi) Python tarafından oluşturulan dosyaları içermez. Varsayılan Mercurial listesi görmezden üzerindeki bu tür kalıpları olmalıdır.
Geliştirme buildout
bootstrap.py: bin / buildout komut dosyası oluşturur. Buildout kullanması gerektiğini, aynı Python yorumlayıcısı ile bu çalıştırın. Gerek hiç bu dosyayı düzenlemek için.
buildout.cfg: Bir test atlet ve paket için bir dokümantasyon oluşturucu yaratan çalışma buildout yapılandırması. paket kendisi geliştirmek yumurta olarak dahil edilir ve buildout başka paketlerin sadece tutturulmuş sürümlerini kullanmak üzere yapılandırılmış. Paketin resmi kalkınma buildout yapılandırmak ama local.cfg yerel özelleştirmeleri koymak için bu düzenleyin. Sürüm pinnings versions.cfg bu dosyanın sürümleri bölüm sadece ilan bu aynı dosyanın buildout bölüm yumurta geliştirmek olan paketleri pinnings geri gerekir / ederken sürümlerinde gidin.
local.cfg: diğer geliştiriciler için hiçbir ilgi buildout yapılandırmasının Yerel özelleştirmeler. Bu Mercurial tarafından göz ardı ediliyor. O andan itibaren bu dosyayı değiştirirseniz, koşmak bin / buildout -c local.cfg. Bu buildout.cfg ve sürüm kontrolü altında olmayan yerel yapılandırmasını tutarak, ilk hantal görünse de böyle bir sürekli entegrasyon sunucu üzerinde paket test olarak kullanım durumları için önemlidir.
sürümleri / versions.cfg:
& Nbsp; şekli Zope'un araç kitinin bir parçası değildir buildout tarafından kullanılan herhangi bir paketleri çivileme. belgeleri oluşturmak için gerekli olan tl.pkg sürümü paket dosyalarını oluşturulan aynı sürüme tutturulmuş. Daha sonra tl.pkg yükseltirken, ihtiyaçlarını çivileme bu sürüm sürümleri arasındaki paket şablonu değişti tüm dosyaları ile birlikte güncellenmesi. Senin paketinde veya buildout gerekli her türlü yumurta sürümlerini pin bu dosyayı düzenleyin.
sürümleri / ZTK-versiyonları-X.Y.Z.cfg:
& Nbsp; Zope araç bir sabit sürümü, bizim sürüm pinnings dahil. Bu yerel bir kopyasını tutmak ağ erişimi olmadan buildout bina izin verir. Bu dosyayı düzenlemek etmeyin.
Genel paket dokümantasyon
Belgelerin standart parçaları içeren ve bu nedenle o yerde ve kendi özel isimler altında beklenen ve Sfenks'in erişilebilir bağımsız olması gerekir paketin üst düzey dizininde bulunan metin dosyaları vardır. Bu dosyalar birebir dahildir telif hakkı ve lisans metin dışında, tam dokümantasyon oluştururken onlar Sfenks tarafından işleniyor geçerli yeniden metin olması gerekir.
README.txt: kendi PyPI sayfa ve Dokümantasyon dizin sayfasının bir parçası olacak paketin amacı, içeriği ve kullanım genel bir bakış. Bu kadar güncel her zaman paket içeriği ile muhafaza edilmelidir.
Changes.txt: Paketin kullanıcılara alakalı paketin herhangi bir değişiklik ile güncelleştirilmesi gerekiyor değişim günlüğü. Dosyanın biçimi zest.releaser ve (kamu Mercurial deposunda "ipucu" sürümü, yani) o anki sürümü PyPI sayfası ve inşa paket belgelere işaret edilecek tarafından anlaşılır.
ABOUT.txt: paketinin ve ikincisinin e-posta adresi gibi yazarların ve paketin belgelerin URL'ler, PyPI sayfasında, sorunu izci ve kaynak kodu yanı sıra güncel günlüğü hakkında bazı göstericiler. O belgeler PyPI de ve hem de yayınlanacak olacak varsayılır; Eğer projeye atanan doğru gelen URL'leri kullandığınızdan emin olun.
COPYRIGHT.txt: telif yıl Zope kamu lisansı, varsayılan sürüm 2.1 kullanılacak lisans, hakkında bazı tavsiyeler de dahil olmak üzere telif hakkı sahibi: paketi için Telif hakkı bilgileri. En azından yıl güncellemek için bu düzenleyin.
License.txt: kullanılan lisansın resmi metnin bir kopyası. Bu farklı bir lisans için döviz hariç düzenleme yok.
Tüm belgeler, Sfenks kullanılarak inşa
doc: Sfenks oluşturulan belgelere sadece ilgili olan herşey. Biz Sfenks giriş dosyaları için sonek .txt kullanın. Sözleşmelerin bir dizi doc dizininin içeriği için mevcut iken, kötü bir şey özgürce değiştirebilirsiniz eğer paketin geri kalanı ne olacak; Sadece geçerli Sfenks girdi kaldığından emin olun.
doc / conf.py: Sfenks yapılandırma. Temelde yapılandırma değerleri tüm kuralları takip ve bu nedenle tl.pkg ithal edilmektedir, böylece tl.pkg.sphinxconf sağlam ithalat ve çağırma tutmalısınız. Eğer metadata ya da sadece bu paket için belgelerin görünümü hakkında bir şey değiştirmek istiyorsanız bu dosyayı düzenlemek gerekir. Sfenks oluşturulan belgeler için sözleşmelere Güncellemeler tl.pkg yükseltme tarafından satın alınacaktır.
doc / index.txt: belgelerin ön sayfası. Bu üst düzey README.txt dosyasını ve tam dokümantasyon bölümlerine işaret içindekiler paket bakış içerir. Bu oluşturulan API belgelerine, paket ve değişim günlüğü hakkında bazı meta bilgileri içerir. Örneğin, üst düzey bölümleri eklemek istiyorsanız bu dosyayı düzenleyin.
doc / narrative.txt:
& Nbsp; anlatı paketi belgelerine kök belge. Bu kaynak ağacında Python modülleri arasında ikamet herhangi doc-test dosyaları toplamak için tasarlanmıştır. Onların belge isimleri desen olmak, toctree direktifi altında dosyaları listelemek için gereken -. (.txt eki olmadan). Bir yorumladı-out örnek dosya listeleme dahildir.
doc / api.txt: üretilen API belgelerine kök belge. API yarı-otomatik autosummary direktif altında, tüm modülleri o andan itibaren otomatik olarak gerçekleşir ki, belgelenmiş olması, bu dosyada listelemek zorunda belgelenmiştir. Bir yorumladı-out örneği modülü listeleme dahildir.
doc / overview.txt:
& Nbsp; Bir saplama üst düzey dosyası README.txt dahil etmek. Gerek bu dosyayı düzenlemek için.
about.txt doc /: paketiyle ilgili Meta bilgileri, üst düzey dosyaları ABOUT.txt, COPYRIGHT.txt ve License.txt birleştirerek. Bu dosyayı düzenlemek gerekmez.
doc / Changes.txt:
& Nbsp; Bir saplama üst düzey dosya Changes.txt dahil etmek. Gerek bu dosyayı düzenlemek için.
doc / requirements.pip:
& Nbsp; belgeleri oluşturmak için gerekli (Sfenks kendisinden başka) Python yumurta bir liste. Bu adresindeki belgeleri oluşturmak içindir. Sen tl.pkg tarafından uygulanan kuralları kullanmak edebilmek için onlarla beyaz listeye edilmesi gerekir. Belgelerinize paket bağımlılıkları değiştirdiğinizde bu dosyayı düzenleyin; Burada yumurta ekstra kullanamazsınız.
tam dokümantasyon Bina
oluşturulan buildout yapılandırma belgeleri oluşturmak için Sfenks çağırır bin / doc bir komut dosyası yükler. Bu komut dosyasını çalıştırmak için, geçerli çalışma dizini paket kök olmalıdır. betik (paketin üst düzey dizine göre) yapı / doc / yerleşik belgeleri koyacağız. Bin / doc geçirilen Seçenekler altında yatan sfenks-inşa komutuna geçti, ama pozisyonel argümanlar işe unutmayın edilecektir.
Sfenks yapılandırma değerleri
Eğer çekirdek Sfenks değişkenlere ek olarak bu yapılandırmak isteyebilirsiniz Varsayılan olarak, Sfenks uzantıları bir dizi, etkindir:
- Sphinx.ext.autosummary
- Sphinx.ext.viewcode
- Sphinx.ext.inheritance_diagram
- Sphinxcontrib.cheeseshop
- Sphinxcontrib.issuetracker
Siz sadece conf.py. içinde ilgili değişkenleri ayarlayarak tl.pkg gelen varsayılan kılabilirsiniz tl.pkg.sphinxconf.set_defaults çağırma sonunda gerçekleşmesi gerekiyor:
source_suffix = '.foo'
ithalat tl.pkg.sphinxconf
tl.pkg.sphinxconf.set_defaults ()
Tersine, sphinxconf değerlerini hesaplamak için conf.py değişkenleri kullanmaya çalışır. Bu değişkenler belirtilirse set_defaults çağrılmadan önce, bu da yapılması gerekmektedir. Şu anda, aşağıdaki değişkenler tanınır:
_year_started: Proje başlatıldı yıl için opsiyonel bir değer. Belirtilen ve cari yıl farklı ise (dokümantasyon binanın zamanında) cari yıl Bu varsayılan, ancak, o "2001-2012 Yazar" gibi bir telif hakkı bildirimi oluşturmak için kullanılır.
_flattr_url: belirtilmişse, bu tam dokümantasyon menü sütunun üstünde görünecek bu proje ve Flattr bağış düğmeleri için bir Flattr şey URL olarak kabul edilir. PyPI sayfasına bir Flattr düğmesi eklemek için, ABOUT.txt içinde "projesini destekleyin" öğesini yorumsuz ve orada da URL doldurun.
_issuetracker_offline:
& Nbsp; gerçek bir değere ayarlanırsa belgeleri ve Sfenks koşmak inşa zaman sunucuya erişmek için deneyin böylece, sphinxcontrib-issuetracker entegrasyon bitbucket entegrasyonu modifiye edilecek ağ erişimi bağımsız kalır. (Diğer izci ile entegrasyon kadar halledilir değil.) Bu, örneğin, izci entegrasyon bazı işlevler devre dışı ama koruyacaktır, düz metin sorunu numaraları tanımayı issuetracker uzantının yeteneği.
Son olarak, tl.pkg.sphinxconf modülü belgeleri gibi bir sistem üzerine inşa edilecek eğer alay modülleri kayıt çağırabilir bir işlevi tanımlar modülleri gibi (bazı kod yükleyemezsiniz ) C uygulanan:
tl.pkg.sphinxconf.register_mock_modules ('Kahire', 'gobject', 'gtk')

Gereksinimler :

• Python