Bina belgeleri¶
BeeWare 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 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 "canlı önizleme" moduna sahiptir.
Canlı önizleme uyarılarla oluşturulacaktır!
Canlı sunum, belgelerinizdeki güncellemeleri yinelemek için kullanılabilir.
Güncelleme işlemi sırasında, bir işaretleme sorunu ortaya çıkabilir. WARNING
olarak kabul edilen sorunlar, standart bir derlemenin başarısız olmasına neden
olur, ancak canlı sunum, derlemeyi sürdürürken konsol çıktısında uyarılar
gösterecek şekilde ayarlanmıştır. Bu, canlı önizlemeyi yeniden başlatmanıza
gerek kalmadan yineleme yapmanızı sağlar.
WARNING ile ERROR farklıdır. ERROR olarak kabul edilen bir sorun ortaya
çıkarsa, canlı hizmet başarısız olur ve yeniden başlatılması gerekir. WARNING
sorunu çözülene kadar yeniden başlatılmaz.
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:
INFO - [11:18:51] Serving on http://127.0.0.1:8000/
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'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:
(venv) $ tox -e docs-all
(venv) $ 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 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.