Bina belgeleri¶
BeeWare Docs Tools belgelerinde herhangi bir değişiklik yapmadan önce, mevcut belgeleri oluşturabileceğinizi doğrulamanız yararlı olacaktır.
Belgeleri oluşturmadan önce, bir geliştirme ortamı kurun.
Python 3.13 yorumlayıcısının yüklü olması ve yolunuzda kullanılabilir olması gerekir (yani, python3.13 bir Python 3.13 yorumlayıcısını başlatmalıdır).
BeeWare Docs Tools belgeleri oluşturmak için tox kullanır. Aşağıdaki tox komutları, projenin kök dizininde bulunan tox.ini dosyasıyla aynı konumdan çalıştırılmalıdır.
Canlı dokümantasyon önizlemesi¶
Belgelerin hızlı düzenlenmesini desteklemek için, BeeWare Docs Tools "canlı önizleme" moduna sahiptir.
Canlı önizleme uyarılarla oluşturulacaktır!
Canlı sunucu, dokümantasyon güncellemeleriniz üzerinde deneme yapmanız için kullanılabilir. Güncelleme işlemi sırasında bir biçimlendirme hatası ortaya çıkabilir. WARNING olarak değerlendirilen sorunlar standart derleme işleminin başarısız olmasına neden olur; ancak canlı sunucu, derleme işlemine devam ederken konsol çıktısında uyarılar gösterecek şekilde ayarlanmıştır. Bu sayede, canlı önizlemeyi yeniden başlatmanıza gerek kalmadan değişikliklerinizi test edebilirsiniz.
Bir WARNING ile bir ERROR arasında fark vardır. Eğer bir ERROR olarak değerlendirilen bir sorun ortaya çıkarsa, canlı sunucu çökecek ve yeniden başlatılması gerekecektir. ERROR sorunu çözülene kadar sunucu yeniden başlatılamayacaktır.
Canlı sunucuyu başlatmak için:
(venv) $ tox -e docs-live
(venv) $ tox -e docs-live
(venv) C:\...>tox -e docs-live
Bu, belgeleri oluşturacak, belgeleri sunmak için bir web sunucusu başlatacak ve belge kaynağında herhangi bir değişiklik olup olmadığını dosya sistemini izleyecektir.
Sunucu başlatıldığında, konsol çıktısında aşağıdakine benzer bir mesaj göreceksiniz:
BİLGİ - [11:18:51] http://127.0.0.1:8000/ adresinde hizmet veriliyor
Bir tarayıcı açın ve verilen URL'ye gidin. Artık belgeleri yinelemeye başlayabilirsiniz. Bir değişiklik algılanırsa, belgeler yeniden oluşturulur ve değiştirilen sayfayı görüntüleyen tüm tarayıcılar otomatik olarak yenilenir.
docs-live ilk adımdır
Canlı sunucuyla çalışmak için docs-live komutunu çalıştırmak, ilk yineleme için tasarlanmıştır. Pull isteği göndermeden önce her zaman yerel bir derleme çalıştırmalısınız.
Yerel yapı¶
Yinelemeyi tamamladıktan sonra, belgelerin yerel bir derlemesini yapmanız gerekir. Bu derleme işlemi, herhangi bir işaretleme sorunu varsa başarısız olacak şekilde tasarlanmıştır. Bu, canlı sunucuda gözden kaçırmış olabileceğiniz her şeyi yakalamanızı sağlar.
Yerel bir derleme oluşturma¶
Yerel bir derleme oluşturmak için:
(venv) $ tox -e docs
(venv) $ tox -e docs
(venv) C:\...>tox -e docs
Bu derlemenin çıktısı, projenin kök dizinindeki _build dizininde olacaktır.
Yerel olarak çevrilmiş bir derleme oluşturma¶
BeeWare Docs Tools'nin belgeleri birçok dile çevrilmiştir. İngilizce belgelerdeki güncellemeler, diğer dil sürümlerinde sorunlara yol açabilir. Pull isteği göndermeden önce tüm sürümlerin çalıştığını doğrulamak önemlidir.
Mevcut tüm çevirilerin bir derlemesini oluşturmak için:
(fiil) $ tox -e docs-all
(fiil) $ tox -e docs-all
(venv) C:\...>tox -e docs-all
Her dil yapısının çıktısı, ilişkili _build/html/<languagecode> dizininde olacaktır. Burada <languagecode>, belirli dil ile ilişkili iki veya beş karakterli dil kodudur (örneğin, Fransızca için fr, İtalyanca için it vb.).
Tek bir derlemede bir sorun bulursanız, tox -e docs-<languagecode> komutunu çalıştırarak o derlemeyi ayrı olarak çalıştırabilirsiniz. Örneğin, yalnızca Fransızca belgeleri derlemek için şunu çalıştırın:
(venv) $ tox -e docs-fr
(venv) $ tox -e docs-fr
(venv) C:\...>tox -e docs-fr
Tek dilli derlemenin çıktısı _build dizininde olacaktır.
Belgelerin linting'i¶
Derleme işlemi Markdown sorunlarını tespit eder, ancak BeeWare Docs Tools stil ve biçimlendirme için "linting" olarak bilinen bazı ek kontroller gerçekleştirir. Lint kontrollerini çalıştırmak için:
(venv) $ tox -e docs-lint
(venv) $ tox -e docs-lint
(venv) C:\...>tox -e docs-lint
Bu, belgelerin aşağıdakileri içermediğini doğrular:
- ölü bağlantılar
- yanlış yazılmış kelimeler
Bir kelimenin geçerli yazımı yanlış yazılmış olarak tanımlanırsa, kelimeyi docs/spelling_wordlist içindeki listeye ekleyin. Bu, kelimeyi yazım denetleyicisinin sözlüğüne ekleyecektir. Bu listeye eklerken şunu unutmayın:
- Programlamaya özgü konuşma dilinde kullanılan bazı kelimeler (örneğin, "apps") ve isimlerin fiil olarak kullanılması (örneğin, "scrollable") dışında, ABD İngilizcesini tercih ediyoruz.
- Ürün adına yapılan her türlü atıfta, ürünün tercih edilen büyük harf kullanımı kullanılmalıdır. (ör. "macOS", "GTK", "pytest", "Pygame", "PyScript").
- Bir terim "kod olarak" kullanılıyorsa, sözlüğe eklenmek yerine kelime olarak (
like this) alıntılanmalıdır.
Belgeleri başarıyla oluşturduktan sonra, belgeleri yazmaya hazırsınız demektir.