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:
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'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 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.