reStructuredText'ten HTML'e Çevirici

Nasıl çalışır?

reStructuredText, Python dünyasının belgeleme dilidir: PyPI paketlerinin README.rst dosyası, Sphinx ile yazılmış dokümantasyon ve birçok açık kaynak projenin CHANGELOG'u bu biçimdedir. Dosyayı GitHub dışında görmek istediğinizde ya da içeriğini bir web sayfasına taşıyacağınızda metni buraya yapıştırmanız yeterlidir. Örneğin paketinizin README.rst'sindeki "Kurulum" başlığı, numaralı adımları, :: ile başlayan pip komutu ve seçenek tablosu sağ panelde h2, ol, pre ve table etiketleriyle çıkar; .. note:: kutusu "Not" başlıklı bir div olur. Başlık seviyesi, docutils kuralıyla aynı şekilde süsleme karakterinin ilk görüldüğü sıraya göre belirlenir: önce = sonra - kullandıysanız = birinci, - ikinci seviyedir. Desteklenen yapılar: alt/üst çizgili başlıklar, paragraf, madde ve numaralı listeler (iç içe), tanım ve alan listeleri, satır bloğu, blok alıntı, geçiş çizgisi, literal ve doctest blokları, basit ve ızgara tablolar, image/figure/code-block ve uyarı yönergeleri, .. _ad: hedefli bağlantılar. toctree, contents, include gibi Sphinx'e özgü yönergeler atlanır ve sonuç satırında sayılır; sessizce yutulmaz. Çıktı HTML kaynağıdır: bir sayfaya gömecekseniz "Gövde", dosya olarak açacaksanız "Tam sayfa" seçin.

Bu araç rst to html, rst to html online aramalarıyla da biliniyor.

reStructuredText (RST) nedir?

reStructuredText, Python topluluğunun 2002'den beri kullandığı düz metin biçimlendirme dilidir; dosya uzantısı .rst'dir. Başlık, altına çizilen ===== ya da ----- satırıyla; vurgu *yıldızla*, kod ``çift ters tırnakla``, bağlantı `metin <adres>`_ kalıbıyla yazılır. Markdown'dan ayrılan yanı yönergelerdir: .. note::, .. image::, .. code-block:: gibi bloklar belgeye genişletilebilir yapı katar. PyPI'daki paketlerin README.rst dosyası, Sphinx ile üretilen dokümantasyon siteleri ve Python'un kendi belgeleri bu dille yazılır; dönüştürme için standart araç docutils'tir.

HTML nedir?

HTML, tarayıcının anladığı sayfa dilidir: başlık <h1>, paragraf <p>, liste <ul>, tablo <table> gibi etiketlerle içeriğin yapısını işaretler. Bu araç RST'deki her yapıyı anlamca eşdeğer HTML etiketine çevirir; uyarı kutuları ve kod blokları sınıf adı alır ki stil bağlanabilsin. Çıktıda görünüm (CSS) yoktur, yalnız yapı vardır — bir blog yazısına ya da içerik yönetim sistemine yapıştırıldığında o sayfanın stilini kendiliğinden alır. Ham HTML ve javascript: adresleri bilerek geçirilmez.

RST ile Markdown arasındaki fark nedir?

İkisi de düz metinle biçimlendirme yapar ama farklı dünyalara aittir. Markdown kısa ve serbesttir: # başlık, **kalın**, [bağlantı](adres); GitHub, forumlar ve not uygulamaları onu kullanır, lehçeleri çoktur ve tablo ya da uyarı kutusu standartta yoktur. reStructuredText daha katı ve daha zengindir: başlık alt çizgiyle yazılır, yönergeler (.. note::, .. code-block::) ve roller (:sup:, :ref:) sayesinde belge genişletilebilir, tablo ve dipnot standardın parçasıdır; bu yüzden Python belgelerinde ve Sphinx'te tercih edilir. Biri diğerine otomatik çevrilebilir ama bire bir değil: Markdown'ın çoğu yapısının RST'de karşılığı vardır, RST yönergelerinin Markdown'da yoktur.

Hangi yönergeler çevrilir, hangileri atlanır?

RST'nin gücü yönergelerdir (.. ad:: ile başlayan bloklar) ve bunların bir kısmı yalnız Sphinx içinde anlam taşır. Bu araç belge içeriği üreten yönergeleri çevirir: image ve figure görsel etiketine, code-block / code / sourcecode dil sınıflı kod bloğuna, note / warning / tip / important / caution / danger / hint / attention / error ise başlığı sayfanın dilinde yazılmış bir uyarı kutusuna dönüşür.

Belge yapısı yerine derleme sürecine ait yönergeler — toctree, contents, include, math, csv-table, list-table — HTML üretmez; gövdeleri çıktıya sızmaz ve sonuç satırında "N desteklenmeyen yönerge atlandı" diye sayılır. Böylece eksik bir bölüm olduğunu çıktıyı taramadan anlarsınız. .. raw:: html bilinçli olarak desteklenmez: RST girdisi üzerinden sayfaya ham HTML enjekte edilemez.

Çıktı neden tarayıcıda 'görünmüyor'?

Sağ panelde gördüğünüz, biçimlendirilmiş sayfa değil HTML kaynağıdır — etiketler açıkça yazılır. Bu bilinçli bir tercihtir: aracın işi metni başka bir yere taşınabilir hâle getirmektir. Sonucu görmek için "Tam sayfa" seçip .html olarak indirin ve dosyaya çift tıklayın; tarayıcı onu normal bir sayfa gibi açar.

Çıktıda stil (CSS) yoktur; uyarı kutuları admonition, kod blokları language-python gibi sınıflarla işaretlenir ki kendi stilinizi kolayca bağlayabilesiniz. Bağlantılarda yalnız http(s), mailto, tel ve göreli adresler korunur; javascript: ve data: adresleri # ile değiştirilir.

• Gövde HTML → blog yazısına, CMS editörüne, mevcut sayfaya yapıştırmak
• Tam sayfa → dosya olarak kaydedip tarayıcıda açmak, e-postaya eklemek
• Markdown kaynağınız varsa → ayrı Markdown'dan HTML'e aracı; iki dil karışık yazılmaz

Sık sorulanlar

RST dosyasını HTML'e nasıl çeviririm?

.rst dosyasını bir metin düzenleyicide açıp içeriğini kopyalayın, sol panele yapıştırın; HTML sağda anında oluşur. Dosya olarak kaydetmek için "Tam sayfa" seçip İndir'e basın. Metin cihazınızdan çıkmaz; dönüşüm tarayıcının içinde yapılır.

Sphinx yönergeleri (toctree, autodoc) neden çıktıda yok?

Bunlar belge içeriği değil, Sphinx'in derleme sırasında başka dosyalardan doldurduğu yer tutuculardır; tek bir metinden üretilemezler. Araç onları atlar ve sonuç satırında kaç yönergenin atlandığını yazar. Başlık, liste, tablo, kod bloğu ve uyarı kutuları gibi içerik yönergeleri eksiksiz çevrilir.

Başlık seviyeleri neden beklediğimden farklı çıktı?

RST'de hangi karakterin hangi seviye olduğu sabit değildir; docutils gibi bu araç da seviyeyi süsleme karakterinin belgede ilk görüldüğü sıraya göre verir. Üst çizgili başlık, aynı karakterin yalnız alt çizgili hâlinden ayrı bir stil sayılır. Belgenin başında = ile başlayıp sonra - kullandıysanız sırasıyla h1 ve h2 alırsınız.

Markdown yapıştırırsam ne olur?

Markdown'ın # başlıkları ve [metin](adres) bağlantıları RST sözdizimi değildir; düz paragraf olarak çıkar ve sonuç satırı yapı bulunamadığını söyler. Markdown için ayrı Markdown'dan HTML'e aracını kullanın. RST'yi tanımanın kolay yolu: başlıkların altındaki ===== ya da ----- çizgileri ve .. ile başlayan yönerge satırları.