Belge, detaylı bir şekilde gözden geçirildi. #233
Conversation
Belge artık hem daha net bir yapıya sahip hem de kullanıcıların ihtiyaç duyduğu bilgileri daha etkili bir şekilde aktarıyor.
Belge, detaylı bir şekilde gözden geçirildi.
Yapılan İyileştirmeler: Hata Mesajları: Dosya bulunamadığında veya başka hatalar oluştuğunda kullanıcıya daha açıklayıcı mesajlar verildi. Kullanıcı Girdi Kontrolü: Kullanıcının boş değer girip girmediği kontrol ediliyor. Eğer bir değer girilmemişse, o URL için işlem yapılmıyor. Dosya Okuma ve Yazma Güvenliği: Dosyalar açılırken FileNotFoundError hataları için kontrol eklendi. Ayrıca, dosyaya yazarken olası hatalar daha iyi yönetildi. Kodun Modülerliği: Kodun bazı bölümleri fonksiyonlar aracılığıyla daha modüler hale getirilebilir. Ancak, burada gereksiz karmaşıklıktan kaçınılarak yalnızca temel iyileştirmeler yapıldı.
Yapılan Düzeltmeler: subprocess hata yönetimi: Hatalar doğru bir şekilde stderr üzerinden kontrol edilip kullanıcıya bildirildi. Hata mesajları: Hata mesajları ve komutların eksik veya yanlış kullanılması durumunda daha açıklayıcı hale getirildi. Multithreading: Yükleme animasyonu (create_status_animation) daha temiz ve düzgün çalışacak şekilde düzenlendi. Dokümantasyon ve argüman vurgulama: highlight_arguments fonksiyonu docstring'lerdeki argümanları etkili bir şekilde vurguluyor.
Bu haliyle scriptin daha güvenli, sürdürülebilir ve kullanıcı dostu oldu
|
@EkremDincel senin eklediğin dosyalarda değişiklik olduğu için sen gözden geçirsen daha iyi olur. |
|
|
||
| Herhangi bir hata oluşmazsa PDF dosyası `/build/latex/` dizininde `yazbelpythonbelgeleri.pdf` adı ile oluşacaktır. |
There was a problem hiding this comment.
Normalde bir aksaklık olursa kişi adımları doğru takip etmediğinden şüphelenir. Ama PDF inşası sıkıntılı bir süreç, bu adımlar her senaryoyu karşılamıyor da olabilir. Buradaki vurgunun sebebi bu manayı iletmekti aslında.
"PDF inşası sürecinde sorun yaşarsanız repo'da issue açabilirsiniz" diye ekleyelim mi?
| Önce yukarıdaki adımları takip edip Sphinx'in kurulumunu gerçekleştirin. | ||
| ### Tek Parça HTML | ||
|
|
||
| Belgeleri diğer formatlarda inşa ettikten sonra da `/scripts/move_documents.py` betiğini çalıştırmayı unutmayın. |
There was a problem hiding this comment.
Bu iki notu silmeye gerek var mı? Özellikle move_documents.py notu kalmalı diye düşünüyorum zira bu betik çalıştırılmadığında yeni inşa edilen HTML, EPUB ve PDF dosyaları repo'ya dahil edilmiyor. build klasörü .gitignore'a dahil çünkü.
| # sphinx produces multiple records instead of a list of records for broken links | ||
| records = [json.loads(i) for i in f.readlines()] | ||
| with open(output_file, 'r', encoding='utf-8') as f: | ||
| # Sphinx, her kırık link için birden fazla kayıt üretir. | ||
| records = [json.loads(i) for i in f.readlines()] |
There was a problem hiding this comment.
Burada çıktı olarak üretilen JSON'daki objelerin bir array içine koyulmak yerine ayrı ayrı satırlara yazılması kastediliyor. Yani aslında dosya bütün hali ile değil, teker teker satırları ile JSON formatına uygun.
Benim yorumum da çok açıklayıcı değildi, Türkçe hali hiç açıklayıcı değil. Bu yorumu düzeltebilir misiniz?
| if replace_with and not replace_with.isspace(): | ||
| success("Link değiştirildi.\n\n") | ||
| else: | ||
| warning("Geçiş yapılıyor.\n\n") |
There was a problem hiding this comment.
"Dosya pas geçiliyor" daha uygun diye düşünüyorum.
| try: | ||
| with open(rst_file, 'r', encoding="utf-8") as f: | ||
| data = f.read() | ||
| except FileNotFoundError: | ||
| warning(f"{rst_file} dosyası bulunamadı. Atlanıyor.\n") | ||
| continue |
There was a problem hiding this comment.
Dosyanın bulunmaması aslında yaşanmaması gereken bir durum, o dosyaların listelisini Sphinx veriyor bize. Yapılan işin gereklilikleri açısından "fatal" bir hata bu, süreç içerisinde gözden kaçırılan bir probleme işaret ediyor. Bulunmayan dosya geçiliyor demek yerine bilgilendirici bir hata yazılıp işlem sonlandırılabilir.
| # URL'yi dosya içinde arama | ||
| if uri not in data: | ||
| alternative_uri = uri.split(":", 1)[0] | ||
| if alternative_uri not in data: | ||
| warning(f"UYARI: URL '{uri}' {rst_file} dosyasının içinde bulunamadı. Bu, ':target:' direktifi ile ilgili olabilir.\n") | ||
| continue | ||
| uri = alternative_uri | ||
|
|
||
| if uri not in data: | ||
| alternative_uri = uri.split(":", 1)[0] | ||
| if alternative_uri not in data: | ||
| warning("WARNING: Can't find the URL {!r} in file {}:{}. Might be about a :target: directive.".format(uri, rst_file, record['lineno'])) | ||
| continue | ||
| uri = alternative_uri |
There was a problem hiding this comment.
lineno bilgisi yeni koda aktarılmamış.
|
@EkremDincel donanım değişikliği yapıyorum. Gün içinde incelemeye çalışacağım. Teşekkürler. |
Belge, detaylı bir şekilde gözden geçirildi. Markdown yapısı iyileştirildi.