reStructuredText ve Sphinx
Bildiğiniz gibi istihza.com‘daki belgeler reStructuredText biçiminde hazırlanıyor. Bu belgeleri farklı biçimlere dönüştürmek için ise Sphinx adlı bir yazılımı kullanıyorum.
Özellikle reStructuredText, belgelendirme çalışmalarıyla uğraşanlar için çok önemli bir araç. Hatta Python programlama dilinin resmi sitesi olan www.python.org‘daki belgelendirme çalışmaları da reStructuredText biçimi kullanılarak yapılıyor. Python geliştiricileri de reStructuredText biçiminde hazırladıkları belgeleri Sphinx adlı yazılım yardımıyla HTML’ye çeviriyorlar. Zaten Sphinx yazılımının geliştiricisi olan Georg Brandl da Python topluluğunun etkin bir üyesi…
Elbette bu önemli konuya istihza.com’da yer vermemek olmazdı. O yüzden Python 2.x bölümüne “reStructuredText ve Sphinx” adlı yeni bir konu ekledim.
Bu konu çok geniş olduğu için henüz tamamlanmadı. Konuları yazdıkça siteye ekleyeceğim. Şimdilik “reStructuredText” ile bir giriş yaptım.
Yeni konu eklemenin yanısıra, Python 2.x bölümünde varolan belgeleri de gözden geçirmeye devam ediyorum. Tabii buna bağlı olarak PDF belgeleri de sürekli olarak tazeleniyor. Yakında istihza.com’da bunun dışında yenilikler de göreceksiniz.
Sevgiler,
istihza
Loading ...
istihza merhaba, ben de geçen biraz kurcaladım rst’yi [1] ama HTML çıktıları seninkiler gibi güzel olmadı. rst2html ile mi aldın çıktıları yoksa Sphinx ile mi? Özellikle kod alanlarındakileri nasıl renklendirebileceğimi çok merak ettim
[1] http://svn.pardus.org.tr/uludag/trunk/doc/tr/reStructuredText.rst
[2] http://ozbekanil.googlepages.com/reStructuredText.html
Merhaba, Docutils paketiyle birlikte gelen rst2html oldukça sade bir HTML çıktısı üretir. Sphinx ise rst belgelerini yorumlayarak çok daha “alımlı” HTML (ve PDF) çıktıları elde etmenizi sağlayan oldukça ayrıntılı bir yazılımdır. Ben istihza.com’daki HTML ve PDF’leri üretmek için Sphinx’ten yararlanıyorum. Sphinx yazılımı, Pygments adlı kütüphaneyi kullanıyor. Bu sayede rst belgelerini Sphinx kullanarak HTML’ye dönüştürdüğünüzde kodlarınız da renkleniyor. Günlük girdisinde bahsettiğim makalenin devamında Sphinx’in nasıl kullanılacağını da anlatacağım.
Bak mesela senin verdiğin reStructuredText.rst dosyasıyla Sphinx’te bir deneme yaptım:
http://istihza.com/denemeler/index.html
Tabi ben burada istihza.com için hazırladığım conf.py dosyası üzerinden gittiğim için sayfada bazı aksaklıklar olabilir. Ayrıca metinde kullandığın resimler benim elimde olmadığı için sayfada resimler görünmez..
Evet, Sphinx çok güzelmiş, öntanımlı ayarlar üzerinde hiç bir değişiklik yapmadan bile oldukça güzel sonuç verdi:
$ sphinx-quickstart
$ make html
$ xdg-open ./_build/html/index.html
Sphinx hakikaten çok yetenekli bir araç. Ama Sphinx’le birlikte kullandığınız Docutils sürümüne dikkat edin. Eski sürümler Türkçe karakter içeren URL’leri düzgün gösteremiyor. Mesela siz kendi ürettiğiniz HTML’de şu sayfadaki URL’nin Türkçe karakterlerini görebiliyor musunuz?
http://istihza.com/denemeler/rest.html#pardus-belgelendirme-calismalarinda-restructuredtext
Burada “ç”, ve “ı” harfleri eski sürüm Docutils kurulu sistemlerde görünmez.
Hımm, dikkat etmemiştim, Türkçe harfler düşmüş:
pardus-belgelendirme-alismalarinda-restructuredtext
kacis-sareti
Ama sorun doğrusal değil gibi? Örneğin birinci bağlantıda ç yok ikincide var. Sorun sadece şöyle oluşuyor galiba: kelimenin ilk harfi Türkçe bir karakterse bunlar düşüyor.
Pardus 2009′daki sürüm şuymuş [1]. Sitesinde de son sürüm olarak bu görünüyor Docutils’in. Siz hangi sürümünü kullanıyorsunuz acaba?
[1] http://paketler.pardus.org.tr/info/2009/devel/source/docutils.html
Ben http://docutils.sourceforge.net/docutils-snapshot.tgz adresindeki sürümü kullanıyorum. Sisteminizdeki docutils klasörü içinde nodes.py adlı bir dosya olacak. Bu dosyanın içinde sonlara doğru “make_id()” adlı bir fonksiyon var. Orada “_non_id_translate” adlı bir sözlük görüyor musunuz? Eğer görmüyorsanız elinizdeki eski sürümdür. Çünkü o sözlük Docutils’in son sürümlerinde eklendi oraya.
Bu arada, normalde Türkçe harflerin hepsinin düşmesi gerekiyor eski sürümlerde. Pardus’taki sürüm 0.6 görünüyor. Yani eski sürüm değil… Acaba Pardus’taki Docutils paketinde bu duruma neden olan bir yama mı var? Paketçiyle konuşmak lazım. Ama siz yine de dediğim gibi nodes.py dosyasının içeriğini kontrol edin.
istihza sendeki nodes.py ile bendekinin arasındaki farklar şöyleymiş [1], bununla ilgili mi acaba, daha denemedim ama yarın bir bakacağım.
[1] http://dpaste.com/164426/
“encode(‘ASCII’, ‘ignore’).decode(‘ASCII’)” satırı, “ASCII” kelimesinin büyük harflerle yazılması nedeniyle Türkçe yereller kullanılırken sorun yaratıyordu. Tıpkı “ROUND_CEiLiNG” hatasında olduğu gibi (http://www.istihza.com/blog/keyerror-round_ceiling.html/). Bu yüzden Docutils geliştiricileri, 0.6 sürümünü yayımladıktan sonra nodes.py’de bir değişiklik yapıp “ASCII” kelimesini “ascii” şeklinde küçük harflerle yazmaya karar verdiler. Konuyla ilgili tartışmayı incelemek için şuraya bakabilirsin: http://sourceforge.net/mailarchive/forum.php?thread_name=alpine.DEB.1.00.0910201625350.16389@lx5.local&forum_name=docutils-develop
Ama sendeki problemin bununla ilgisi yok. Eğer mümkünse Docutils paketini sistemden kaldırıp, snapshot sürümünü kendin kaynaktan derlemeyi deneyebilirsin. Ben Sphinx, Jinja2, Pygments ve Docutils paketlerini kaynaktan derleyerek kullanıyorum. Çünkü Ubuntu’daki Docutils ve Sphinx paketleri bayat… Ayrıca Docutils’i kaynaktan kurduktan sonra, başka bir paketin depodaki Docutils sürümünü kurmamasına da dikkat ediyorum.
Yeni belge harika…
Sağol Burak… Bu arada bu Pazar işin var mı?
e-posta attım