Weblate belgelerine katkıda bulunun

İstediğiniz belgeler sayfasını iyileştirebilirsiniz. Bunun için sayfanın sağ üst köşesindeki GitHub üzerinde düzenle düğmesine tıklayarak kolayca yapabilirsiniz.

Belgeleme kuralları

Lütfen yazarken şu kurallara uyun:

  1. Geçerliyse, belgenin bir bölümünü kaldırmayın.

  2. Açık ve kolay anlaşılır bir dil kullanın. Teknoloji belgeleri yazıyorsunuz, şiir değil. Belgeleri okuyacak herkesin ana dili İngilizce değildir, düşünceli olun.

  3. Emin değilseniz sormaktan çekinmeyin. Düzenleme yaparken bazı özellikler ile ilgili soru sormanız gerekiyorsa, yanıtı almadan önce belgeleri değiştirmeyin. Özetle: Değiştirin ya da sorun. İkisini aynı anda yapmayın.

  4. Belgeleri izlerken açıklanan işlemleri yaparak değişikliklerinizi doğrulayın.

  5. Onaylama ve birleştirmenin daha kolay ve hızlı yapılması için çekme isteğinde küçük değişiklik parçaları gönderin.

  6. Büyük bir makaleyi yeniden yazmak ve yapısını değiştirmek istiyorsanız, bunu iki adımda yapın:

    1. Yeniden yazın

    2. Yeniden yazma onaylandıktan, iyileştirildikten ve birleştirildikten sonra, başka bir çekme isteğinde paragrafların yapısını değiştirin.

Belgeleri yerel olarak oluşturmak

Belgeler yerel olarak da düzenlenebilir ve oluşturulabilir, Python gereksinimleri docs bağımlılık grubunda pyproject.toml içinde bulunabilir. Zaten tam geliştirme ortamını kullanıyorsanız, uv sync --all-extras --dev yeterlidir. Yalnızca belge çalışmaları için uv sync --group docs yeterlidir.

Önerilen yerel iş akışı:

make -C docs update-docs
./ci/run-docs

ci/run-docs sarmalayıcı, belgeleri hata olarak kabul edilen uyarılarla oluşturur.

CI documentation, release notes, and linkcheck builds reuse cached intersphinx inventories. The Intersphinx inventories workflow refreshes them daily and can also be run manually from GitHub Actions on the default branch. Failed refreshes retain the last valid inventories and are reported as workflow failures.

Inventories are stored in docs/_build/intersphinx. Builds use upstream inventories when a local copy is missing, including after CI cache eviction or when adding an inventory URL. Local and Read the Docs builds do not require the cache. To refresh local copies for all documentation languages, run:

languages=$(uv run --no-project scripts/list-documentation-languages.py)
uv run python docs/_ext/intersphinx_cache.py --languages "${languages#languages=}"

The inventory cache does not eliminate network requests for checking destination pages during linkcheck builds.

İpucu

Belgeleri oluşturmak için graphviz programının kurulmuş olmasına da gerek duyacaksınız.

Belgeleri çevirmek

Belgeleri çevirebilirsiniz.

Oluşturulmuş belgeleri parçalarını güncellemek

Birkaç belge bölümü, koddan oluşturulan kalıpları kullanır. Bunları yenilemenin yeğlenen yolu:

make -C docs update-docs

Bu hedef, aşağıdakiler ile belgeler tarafından şu anda kullanılan parçaları yeniden oluşturur:

  • eklenti etkinlikleri, iç eklentiler ve yaygın eklenti parametreleri

  • makine çevirisi hizmetleri

  • dosya biçimi parametreleri ve dosya biçimi özellik tabloları

  • izinler ve hazır roller

  • denetimler ve denetim imleri

Kendiliğinden oluşturulmuş parçalara eklemek yerine ana belge sayfasında el ile güncellenen içeriği tutun. Örneğin, Eklentiler içinde etkinlikler, iç eklentiler ve yaygın eklenti parametreleri için oluşturulmuş üç dosya bulunurken, eski eklentiler doğrudan sayfada tutulur.

Yalnızca bir parçayı yeniden oluşturmanız gerekiyorsa, bireysel yönetim komutları Yönetim komutları içinde belgelenmiştir ve update-docs tarafından kullanılan tam komutlar docs/Makefile içinde bulunabilir.