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.

2 Beğeni

Merhabalar @dildeolupbiten.

Bir süredir pyglet öğreniyorum.Şimdi belgelere gittim ve Ctrl + F yapıp “pyglet” araması yaptım,bir sonuç bulamadım.Demek ki yok.Bildiklerimi paylaşmak,ve belgelere yaptığım eklemeleri başka platformlarda (YouTube,Udemy…) paylaşmak istiyorum.Nasıl yapacağım konusunda yardımcı olabilir misiniz? Sayfanın bütün HTML kodlarını ben mi yazacağım mesela?

Merhabalar,

Tabi yardımcı olmaya çalışayım:

  1. GitHub - yazbel/python-istihza: İstihza Python Belgeleri, en kapsamlı Türkçe Python belgelendirmesi adresindeki repoyu forklayın. Forkladığınız reponun klonunu bilgisayarınıza indirin.

  2. Ana dizinin içinde sphinx_source isminde bir klasör yer aldığını göreceksiniz. Bu klasörün içinde rst uzantılı belgeler yer alır. Belgeleyi hazırlarken bu belgelere bakarak belgeyi nasıl yazmanız gerektiğini öğrenebilirsiniz.

  3. Yazacağınız belge 3. şahısların yazdığı bir kütüphane olduğu için bu belgeyi sphinx_source klasörünün içinde yer alan Ucuncu_taraf_moduller klasörünün içine atmalısınız.

  4. Eğer yazdığınız belge tek bir dosyadan oluşuyorsa, o dosyanın adını Ucuncu_taraf_moduller klasörünün içinde yer alan index.rst dosyasına yazmanız gerekir. Eğer belgeniz birkaç rst dosyasından oluşuyorsa, belgeleri bir klasör içine yerleştirebilirsiniz. Ancak bu sefer o klasör için bir index.rst dosyası oluşturmanız gerekir. Ucuncu_taraf_moduller klasöründe yer alan diğer kütüphanelerin nasıl düzenlendiğine bakarak klasörünüzün index.rst dosyasını düzenleyebilirsiniz. Belgeleri istenen biçime göre hazırladıktan sonra, oluşturduğunuz klasörü tanıtmak için, Ucunu_taraf_moduller klasöründeki index.rst dosyasına klasörünüzün index.rst dosyasını tanıtmanız lazım.

  5. Belgede kullanacağınız resimler varsa bu resimleri, ana dizinde yer alan _images klasöründe tutmanız lazım. rst dosyalarına nasıl resim eklenir öğrenmek için veya rst’de hangi komutların hangi işleme yol açtığını öğrenmek için internette araştırma yapabilirsiniz.

  6. Belge inşa etme işlemi için sphinx kütüphanesi kullanılır. Bilgisayarınıza sphinx’in son sürümünü indirin.

  7. Belgeniz hazır olduktan sonra ve sisteminize de sphinx’i yükledikten sonra artık sıra belgelerin inşa edilmesine gelir.

İnşa etmek için Linux’de yazılması gereken ifade şudur:

make html

Windows için ise şu:

make.bat html
  1. Belgeler inşa edildikten sonra ana dizinde bulunan move.py dosyasını çalıştırın.
  2. Üzerinde değişiklik yaptığınız repoyu kendi git hesabınıza push edin. Sonra da bir pull request gönderin. Şayet belgeniz, istendiği gibi yazılmışsa çekme isteği onaylanır. Şayet bazı hatalar tespit edilirse, tespit edilen hatalarla alakalı tavsiyeler alırsınız ve çekme isteğiniz onaylanmaz. Ancak belge üzerinde düzeltilmesi gereken yerleri düzelttikten sonra bu mesajın 7. maddesinden sonraki adımlar tekrar uygulamanız gerekir.

Yukarıdaki yazıda HTML kodlarının sphinx tarafından oluşturulacağından, sizin sadece rst uzantılı belge dosyaları hazırlamanız gerektiğinden bahsettim.

Not: Eğer sizin reponuz, fork ettiğiniz repodan geride kalmışsa, fork ettiğiniz reponun verilerini çekip (fetch), reponuzla verilerini çektiğiniz repoyu birleştirmeniz gerekir (merge). Aksi taktirde uyumsuzluklar oluşur. Aşağıdaki bağlantı size bu konuda bilgi verebilir.

https://kodcu.com/2015/03/pull-request-nedir-nasil-yapilir/

2 Beğeni

PC başına geçtiğim zaman yapmaya çalışacağım.

Django belgeleri ceviri diye biliyorum, ama yazbel belgelerinde -django dokumantasyonunda olmadigi halde- ReCaptcha anlatimi var. Ben de ceviri mi yapayim, yoksa istedigim gibi yazayim mi?

Nasıl istiyorsanız öyle yazın. Hazırladığınız belge yayınlanmaya uygun bulunursa yayınlanır.

1 Beğeni

Bunu ben yazmıştım. Sebeplerine gelecek olursak
İlk sebebi o öğreticide bir anket uygulaması tasarlıyor olması. Piyasada genelde blog uygulaması tasarlanırken bu durum ilgimi çekmişti.
Daha önce sitede çevirilerle karşılaşmış olmamın çeviri olmasında etkisi büyüktür.
O dönemdeki bilgi birikimim belge yazmaya yetecek seviyede değildi. (Bugün bile yeterince yüksek bir birikimim yok bence.) O yüzden çeviri mantıklıydı. O ara belgelere sürekli bir şeyler eklemek istiyordum. Bu yüzden kötü de olsa bir belge yazdım.

Bu çeviri ingilizce bilen biri için garip bir durum. Sonuna kadar katılıyorum.

O dönem bir de channels anlatımı yapmayı planlıyordum. Ancak sebebini bilmiyorum ama yapamadım. Bir de o belgelerin son belgesi kalmıştı. Tamamlayamadan belgeler eskidi.

Bir ara vakit bulursam yeni bir uygulama yazarak tekrar yapayım onu.

Sihirli metodların belgelerde olması iyi olurdu bu konu hakkında türkçe kaynak eksikliği var.Gerçi bir çok konu hakkında türkçe kaynak eksikliği var yazbel de olmasa benim gibi İngilizce bilmeyenlerin hali nice olurdu :slight_smile: