Python Belgelerine Katkı

Merhaba. Adım Ekrem. İlk programlama dilim olan Python’u sitenizdeki belgeler sayesinde öğrendim. Türkçe bir kaynak olarak gerçekten çok faydalı olduğunu düşünüyorum. Site yöneticilerine ve belgelerde emeği geçen herkese teşekkürlerimi iletiyorum. Bir süre sonra bu belgeler de yeterli gelmemeye başladı tabii. Yabancı kaynaklardan da çok şey öğrendim. Öğrendikçe ne kadar çok konunun eksik olduğunu görüyorsunuz aslında. Ben de belgelere katkıda bulunmak istedim ama bir sorum olacak:

  • Döküman yazarlarımız konuları ilgi çekici ve çok sıkmayacak bir şekilde anlatmışlar ama ben bu kadar iyi yazabilir miyim bilmiyorum. Çoğunlukla yazılarım daha ciddi ve makale tarzı oluyor. Bu konuda ne yapmalıyım? Bir problem olur mu?

Eklemek istediğim konulara gelirsek, ne kadar vaktim olur ve ne kadarını yetiştirebilirim bilmiyorum ama şu konular hakkında katkıda bulunmak istiyorum (Bazıları dökümanda olduğu halde gözümden kaçmış veya unutmuş olabilirim, okumayalı 6 ay oluyor):

  • Walrus Operatörü ( 3.8 versiyonu ile yeni geldi )
  • Generatörler
  • Bezeyiciler (Decorator)
  • Metasınıflar
  • Sihirli methodlar (Magic methods)
  • Coroutines

Bir de unutmadan söyliyim , Django konusunun tamamını resmi siteden direkt çevirmeniz biraz garip olmuş :smiley:

Merhaba, hoş geldiniz Ekrem Bey kardeşim.

Bir problem olacağını sanmıyorum. Siz doküman haline getirmek istediğiniz konuyu yazmaya başlayın, düzeltilmesi gereken kısımlar olursa zaten bu kısımlar size söylenir siz de gerekli düzeltmeleri yaparsınız. Dikkat etmeniz gereken şey şu: Belgeleri rst uzantılı dosyalara yazmanız gerekiyor. Github adresinden yazbel belgelerini indirin, sphinx-source isimli klasörde dokümanların kaynak dosyaları var. Onları inceleyerek belgeyi yazarken nasıl bir format kullanmanız gerekiyor görebilirsiniz. Bu dosyalardaki formata uygun şekilde makalenizi yazdıktan sonra da index.rst dosyasına yazdığınız makalenin ismini ekleyin. index.rst dosyasını incelerseniz, yazdığınız dosyayı index.rst dosyasında nasıl tanıtmanız gerektiğini de anlayacaksınız diye tahmin ediyorum. Son olarak güncel belgeleri kendi github hesabınıza yükleyin. Sonra da bir çekme isteği gönderin. Çekme isteği eğer belgenizde bir sorun yoksa kabul edilir, düzeltilmesi gereken bir takım şeyler varsa da reddedilir, onları düzeltir tekrar çekme isteği gönderebilirsiniz.

Eğer yardıma ihtiyacınız olursa, çekinmeden yardım isteyebilirsiniz, elimizden geldiğince yardımcı olmaya çalışırız.

Kolay gelsin, iyi çalışmalar.

Neden?
Hal-i hazirda binlerce kisiye Django ogrenmis bir dokumani Ingilizce bilmeyen Turklerin kullanimina acmanin nesi garip? Ayni amaci guden bir dokumani sifirdan yazmak garip olurdu.

Aradigin kelime yasadışı olabilir, zira sitede copyright ibaresi var ama dokumanin lisansina dair bir ibare yok. Copyright ibaresindeki “and contributors” atfina ve kutuphanenin ve komunitenin genel durusuna bakacak olursak dokuman cok buyuk ihtimalle ozgur bir lisansa sahip ama ~2 dakikalik arastirmayla ben bulamadim.

Neden?
Hal-i hazirda binlerce kisiye Django ogrenmis bir dokumani Ingilizce bilmeyen Turklerin kullanimina acmanin nesi garip? Ayni amaci guden bir dokumani sifirdan yazmak garip olurdu.

İngilizce dökümanı direkt Türkçe’ye çevirince bana konular çok anlaşılır gelmemişti, faydalanan varsa çeviren sağ olsun. Yasadışı kısmı aklıma gelmemişti.

Bilgilendirmeniz için teşekkür ederim. index.rts ye yeni dökümanları nasıl ekleyeceğimi anladım. Ancak dökümanı yazarken bazı hatalar yapma ihtimalim var. Dökümanı yazdıktan sonra nasıl sitede gözüken haline çevirip doğru gözüküyor mu diye bakabilirim? Sphinx mi kullanmam gerekiyor?
Ayrıca gördüğüm kadarıyla sublime text, .rts uzantılı dosyaların biçimlendirme şeklini algılayabiliyor. Bu doğru yazdığımı anlamam için yeterli olabilir.

İsterseniz sphinx ile html dosyası oluşturup belgenin nasıl göründüğüne bakabilirsiniz. İsterseniz sublime text’i kullanabilirsiniz, isterseniz github’da da deneyebilirsiniz.

Github da Bezeyiciler ile alakalı bir pull request gördüm ancak dökümantasyonda bu konuyu bulamadım. Bu konu eklenecek mi? Ben de o konudan bahsedecektim, ona göre yazamaya başlayayım.

İsterseniz bezeyiciler konusunu şimdilik askıya alın, @ismailarilik yanılmıyorsam bu ara biraz yoğun. Daha sonra çekme isteklerine bakacaktır diye tahmin ediyorum.

Olur, problem değil. Anlatacağım diğer konular için gerekli değil zaten.

reStructuredText’in çalışma şeklinden dolayı bir problem yaşamaktayım. Sihirli metotların alt başlıklarına ‘add’ (ki bu forumda da yanlış yazdı. Boşluksuz bir şekilde __ add __ olması lazım) gibi bir metot yazdığımda link olarak algılanıyor. Bunu nasıl düzeltebileceğim ile ilgili bir bilginiz var mı? Yoksa sizin tarafınızdan html ye dönüştürülürken düzeltilebilir mi?

Şu ana kadar yaptığım eklemeleri githubıma yükledim.


Daha ekleyeceğim birbiri ile alakalı konular olduğu için şuanda pull request yapmadım. Eleştirilere açığım. Daha iyi anlatılabileceğini düşündüğünüz yerler varsa , eksik veya yanlış bir yer görüyorsanız lütfen bildirin. Halen eksikler bulunmakta ancak konu sayısı daha da artmadan temelleri sağlam olsun diye bu yazıyı yazdım. Yorumlarınızı bekliyorum.

1 Like