reStructuredText

Giriş

Diyelim ki bir program yazdınız ve kullanıcılarınıza yol göstermek amacıyla, bu program için bir kullanma kılavuzu oluşturmak istiyorsunuz. Ya da benim yaptığım gibi, bir programlama dilini öğreten bir site işletiyor da olabilirsiniz. Eğer hazırladığınız belgeleri internet üzerinde yayımlayacaksanız bu belgeleri HTML biçiminde düzenlemeniz gerekir. İşte bu noktada, belgelendirme işlemi tam bir çileye dönüşür. Çünkü yazdığınız belgeleri internet üzerinde sergilenebilecek bir hale getirmek, asıl belgeleri hazırlamaktan daha vakit alıcıdır. Yani asıl yapmanız gereken işe ayıracağınız zamanı, siteyi yayımlanabilir hale getirmeye harcadığınızı farkedersiniz. Üstelik tek tek hazırladığınız HTML belgelerinin bakımını yapmak da bir hayli meşakkatlidir.

Bunun dışında, oluşturduğunuz belgeleri farklı biçimlerde yayımlamak istediğiniz zaman da büyük zorluklarla karşılaşırsınız. Örneğin oluşturduğunuz HTML belgelerini daha sonra PDF olarak da okurlarınıza sunmak isterseniz omzunuzdaki yük daha da artacaktır.

İşte bu noktada “reStructuredText” ya da kısa adıyla “rst” devreye girer. Eğer belgelerinizi HTML veya herhangi başka bir biçimde hazırlamak yerine rst biçiminde hazırlarsanız, bu belgeleri daha sonra pek çok farklı biçime dönüştürmek epey kolay olacaktır. Yani bir kez rst biçimli belge hazırladıktan sonra bu belgeleri daha sonra isterseniz PDF, HTML ve ODT gibi biçimlere dönüştürebilirsiniz. Peki bu rst denen şey tam olarak nedir? Gelin isterseniz bu sorunun cevabını bulmaya çalışalım.

Bu soruyu çok kısa bir şekilde şöyle cevaplayabiliriz: reStructuredText bir metin işaretleme dili/sistemidir. Peki “metin işaretleme” ne demek? Şöyle düşünün: Diyelim ki elinizde dümdüz bir metin var. Mesela şöyle bir şey:

Python Programlama Dili

Python Kelimesinin Anlamı

Her ne kadar Python programlama dili ile ilgili çoğu görsel malzemenin
üzerinde bir “piton” resmi görsek de, “Python” kelimesi aslında çoğu
kişinin zannettiği gibi “piton yılanı” anlamına gelmiyor. “Python
Programlama Dili”, ismini Guido Van Rossum’un çok sevdiği, Monty Python
adlı altı kişilik bir İngiliz komedi grubunun Monty Python’s Flying Circus
adlı gösterisinden alıyor.

Burada “Python Programlama Dili” bir üst başlıktır. “Python Kelimesinin Anlamı” ise bir alt başlık... Bunun altında ise asıl metin yer alıyor. Şimdi bu metni şu hale getirelim:

***********************
Python Programlama Dili
***********************

Python Kelimesinin Anlamı
=========================

Her ne kadar Python programlama dili ile ilgili çoğu görsel malzemenin
üzerinde bir “piton” resmi görsek de, “Python” kelimesi aslında çoğu
kişinin zannettiği gibi “piton yılanı” anlamına gelmiyor. “Python
Programlama Dili”, ismini Guido Van Rossum’un çok sevdiği, Monty Python
adlı altı kişilik bir İngiliz komedi grubunun Monty Python’s Flying Circus
adlı gösterisinden alıyor.

İşte bu şekilde yukarıdaki metni reStructuredText adlı işaretleme dilini kullanarak “işaretlemiş” olduk. Burada kullandığımız işaretler “*” ve “=”.

Elbette rst işaretleme dili sadece bu işaretlerden ibaret değildir. Düz bir metni özel işaretlerle işaretleyerek farklı biçimlerde metinler ortaya çıkarabiliriz. Ancak bir metni sadece bu tür işaretlerle işaretlemek tek başına hiç bir işe yaramaz. Burada bizim ihtiyacımız olan şey bu işaretleri anlayacak özel bir programdır. Şöyle düşünün: Diyelim ki Python programlama dilini kullanarak şu kodları içeren bir dosya oluşturdunuz:

#!/usr/bin/env python
#-*- coding: utf-8 -*-

for i in range(10):
    print i

Bu kodları içeren dosya bu haliyle hiç bir işe yaramaz. Sizin ihtiyacınız olan şey, bu dosyada yazılı kodları tanıyacak ve yorumlayacak özel bir programdır. Burada o özel program Python’dur. Dolayısıyla yukarıdaki kodların bir işe yarayabilmesi için sisteminizde Python’un kurulu olması gerekir... İşte aynen burada olduğu gibi, rst işaretleme dilini kullanarak oluşturduğunuz metinlerin de bir işe yarayabilmesi için bu rst işaretlerini anlayacak bir programa sahip olmalısınız. Piyasada rst işaretleme dilini anlayan farklı programlar bulunur. Biz bu bölümde bunlar içinde en gelişmişlerinden biri olan Sphinx adlı yazılımı kullanacağız. Ancak o kısma geçmeden önce isterseniz durumu biraz daha somutlaştırmak için bir uygulama yapalım.

Dediğimiz gibi, rst dilini anlayan farklı programlar vardır piyasada. Siz bunlardan birini edinip rst belgeleriyle çalışmaya başlarsınız. Ama bir de internet üzerinden hizmet veren bir rst servisi de bulunur. Bu servis yardımıyla oluşturduğunuz rst belgelerini çok hızlı bir şekilde test edebilirsiniz. Bu servise ulaşmak için http://www.tele3.cz/jbar/rest/rest.html adresine gidelim. Orada gördüğümüz kutucuğa yukarıda yazdığımız şu rst metnini yapıştıralım:

***********************
Python Programlama Dili
***********************

Python Kelimesinin Anlamı
=========================

Her ne kadar Python programlama dili ile ilgili çoğu görsel malzemenin
üzerinde bir “piton” resmi görsek de, “Python” kelimesi aslında çoğu
kişinin zannettiği gibi “piton yılanı” anlamına gelmiyor. “Python
Programlama Dili”, ismini Guido Van Rossum’un çok sevdiği, Monty Python
adlı altı kişilik bir İngiliz komedi grubunun Monty Python’s Flying Circus
adlı gösterisinden alıyor.

Bu metni o kutucuğa yapıştırdıktan sonra alt tarafta görünen “render” düğmesine bastığımızda karşımıza yukarıdaki rst belgesinin HTML biçiminde yorumlanmış hali gelecek. Gördüğünüz gibi, yukarıda “*” ile işaretlediğimiz kısım metnin ana başlığı, “=” ile işaretlediğimiz kısım ise metnin alt başlığı oldu.

Böylece bir rst metninin neye benzediği ve bu metnin yorumlanması sonucu nasıl bir şeyin ortaya çıktığı konusunda temel bir fikir edinmiş olduk. Artık reStructuredText’in derinliklerine dalabiliriz.

RestructuredText Dosyaları ve rst2html Betiği

Giriş bölümünde, yazdığınız bir rst belgesini test etmek için http://www.tele3.cz/jbar/rest/rest.html adresinden yararlanabileceğinizi söylemiştik. Ancak bu yol her zaman tercih edilmeyebilir. Mesela kendiniz rst belgelerini html belgelerine dönüştürmek isterseniz bu yöntem işinize yaramayacaktır. Bu bölümde size rst belgelerini nasıl kaydedip farklı biçimlere dönüştürebileceğinizi anlatmaya çalışacağım.

Öncelikle şunu söyleyeyim. Bir rst dosyası mutlaka .rst uzantısına sahip olmak zorunda değildir. rst belgelerinizi .txt uzantısıyla da kaydedebilirsiniz. Mesela yukarıdaki verdiğimiz örnek rst metnini “deneme.rst” veya “deneme.txt” adıyla bilgisayarınıza kaydedin. Yani elinizde, içeriği şu olan, “deneme.txt” veya “deneme.rst” adlı bir dosya olsun:

***********************
Python Programlama Dili
***********************

Python Kelimesinin Anlamı
=========================

Her ne kadar Python programlama dili ile ilgili çoğu görsel malzemenin
üzerinde bir “piton” resmi görsek de, “Python” kelimesi aslında çoğu
kişinin zannettiği gibi “piton yılanı” anlamına gelmiyor. “Python
Programlama Dili”, ismini Guido Van Rossum’un çok sevdiği, Monty Python
adlı altı kişilik bir İngiliz komedi grubunun Monty Python’s Flying Circus
adlı gösterisinden alıyor.

Şimdi bu rst dosyasını bir html dosyasına dönüştüreceğiz. En başta da söylediğim gibi, rst belgeleri tek başına bir işe yaramaz. Bu belgeleri farklı biçimlere dönüştürebilmek için bazı özel programlardan yararlanmamız gerekir. Dediğim gibi, biz bu iş için Sphinx adlı bir yazılımdan faydalanacağız. Ama Sphinx bu alandaki tek dönüştürücü yazılım değildir. Bu yazılım, oldukça ayrıntılı ve yeteneklidir, ancak şu aşamada bizim için biraz ağır kaçabilir. O yüzde biz bu giriş bölümünde şimdilik “rst2html” adlı bir betikten yararlanacağız. Bu basit betik sayesinde, hiç başka şeylerle kafamızı karıştırmadan, reStructuredText denen şeye aşinalık kazanacağız. Peki biz bu “rst2html” adlı betiği nereden edineceğiz? Bu betik “docutils” adlı paketin bir bileşenidir. GNU/Linux kullanıcıları, dağıtımlarının paket yöneticisi aracılığıyla Docutils’i sistemlerine kurabilir. Eğer Ubuntu GNU/Linux’u kullanıyorsanız şu komutu vermeniz yeterli olacaktır:

sudo aptitude install python-docutils

Windows kullanıcıları ise http://docutils.sourceforge.net/docutils-snapshot.tgz adresinden, en son Docutils paketini indirebilir. Bu paketi indirdikten sonra, paketi açıp “docutils” klasörü içinde şu komutu vererek Docutils’i sisteminize kurabilirsiniz:

python setup.py install

Docutils paketini dağıtımlarının paket yöneticisinde bulamayan veya Docutils’in en son sürümünü kullanmak isteyen GNU/Linux kullanıcıları da yukarıdaki adresten indirdikleri Docutils paketini aynı komut yardımıyla sistemlerine kurabilir. Ancak GNU/Linux kullanıcıları yukarıdaki komutu yetkili kullanıcı olarak vermeye özen göstermeli...

Dediğim gibi, rst2html adlı betik Docutils paketinin bir bileşenidir. Dolayısıyla Docutils paketini sistemimize kurduktan sonra bu betiğe erişebileceğiz. Şimdi yukarıda oluşturduğumuz “deneme.txt” veya “deneme.rst” dosyasının bulunduğu klasöre giderek şu komutu veriyoruz:

rst2html deneme.txt > deneme.html

Tabii ben burada dosya adının “deneme.txt” olduğunu varsaydım. Eğer siz farklı bir dosya adı kullandıysanız yukarıdaki komutu ona göre düzenlemeniz gerekir.

Yukarıdaki komutu verdikten sonra, komutu verdiğimiz klasör içinde “deneme.html” adlı bir dosya oluştuğunu göreceğiz. Bu dosyayı herhangi bir internet tarayıcısı yardımıyla görüntüleyebilirsiniz. Bu dosyayı bir metin düzenleyici ile açarsanız, bunun standart bir html dosyası olduğunu göreceksiniz.

Oluşan bu html dosyasını internet tarayıcınız yardımıyla açtığınızda rst belgesindeki özel işaretlerin nasıl yorumlandığına dikkat edin. Gördüğünüz gibi “*” işareti ile gösterilen kısım html belgesinde üst başlık olarak, “=” işareti ile gösterilen kısım ise alt başlık olarak yorumlanmış. Başlıkların altında yer alan işaretsiz kısım ise html belgesine normal bir paragraf olarak yerleştirilmiş.

Paragraf Stilleri

Bundan önceki bölümlerde reStructuredText’in yapısı hakkında bir-iki şey söyledik. Öğrendiğimiz gibi, bir rst belgesi, özel bazı işaretlerden oluşuyor. Mesela “*” işaretinin üst başlıkları belirtmek için, “=” işaretinin ise alt başlıkları belirtmek için kullanıldığını öğrenmiştik. Ancak elbette reStructuredText bunlardan ibaret değildir. İşte biz de bu bölümde bir rst belgesi içinde hangi işaretlerin hangi amaçlara hizmet etmek üzere kullanılabileceğini tartışacağız.

Dilerseniz en baştan başlayalım:

Bölüm Başlıkları

reStructuredText biçimli metinleri oluştururken, bölüm başlıklarını göstermek için özel bazı işaretlerden yararlanıyoruz. Esasında bu işaretlerin ne olacağı tamamen size kalmış. Yani bu konuda çok sıkı bir zorlama yok. Buradaki en temel kural, bölüm başlıklarını gösterirken harf veya sayı kullanmamak. Yani - ` : ' " ~ ^ _ * + # < > işaretlerinden herhangi birini rahatlıkla kullanabilirsiniz. Önemli olan, kullandığınız işaretlerde tutarlı olmanızdır. Mesela biz yukarıda verdiğimiz örnekte “*” işaretini üst başlıklar için, “=” işaretini ise alt başlıklar için kullandık. Ben “*” işaretini kullanırken, metin içinde üst başlıklar daha kolay ayırt edilebilsin diye “*” işaretini hem başlığın üst tarafına hem de alt tarafına yerleştirdim. Siz isterseniz bu işaretler yerine başkalarını da kullanabilirsiniz. Örneğin üst başlıkları belirtmek için “_” işaretini, alt başlıkları göstermek için ise “:” işaretini tercih edebilirsiniz. Dediğim gibi, önemli olan tutarlı olmanız ve aynı seviyedeki başlıkları bütün metin boyunca aynı işaretle göstermenizdir. Ben bu durumlar için size şöyle bir şablon önerebilirim:

**********
ÜST BAŞLIK
**********

Alt Başlık
==========

Alt alt-başlık
^^^^^^^^^^^^^^

Elbette siz de isterseniz kendi göz zevkinize uygun başka bir şablon belirleyip her zaman onu kullanabilirsiniz. Mesela Docutils’in resmi sayfasında kullanılan başlık şablonunu inceleyerek bir fikir edinebilirsiniz. Sayfaya http://docutils.sourceforge.net/index.txt adresinden erişebilirsiniz. Docutils’in sayfasındaki html belgelerinin rst kaynaklarını görmek için, her sayfanın en altında yer alan “View document source” bağlantısını takip edebilirsiniz. İnternet üzerinde bulunan belgelerin rst kaynaklarını incelemek size bu belge biçimi hakkında önemli ipuçları verecektir.

rst belgelerindeki başlıklar hakkında söylenmesi gereken en önemli şeylerden biri, kullandığınız işaretlerin sayısıdır. Bir başlığın alt tarafına yerleştireceğiniz işaretler en az o başlıktaki karakter sayısı kadar olmalıdır. Yani şöyle bir kullanım hatalı olacaktır:

***
BAŞLIK
***

Burada üst ve alt tarafa en az altı adet “*” işareti yerleştirmemiz gerekir:

******
BAŞLIK
******

Paragraflar

reStructuredText biçimli metinler yazarken paragrafları göstermek için özel herhangi bir işaret kullanmıyoruz:

*****
Çilek
*****

Çilek (Fragaria), gülgiller  (Rosaceae) familyası içinde yer alan
bir bitki cinsi ve bu cins içinde yer alan türlerin meyvelerinin
ortak adıdır.

Dünyada, adlandırılmış 20'den fazla çilek türü vardır; ayrıca, çeşitli
melezler ve kültivarlar da bulunur. Dünya çapında ticari olarak en çok
yetiştirilen çilekler, bahçe çileği olarak adlandırılan Fragaria × ananassa
melezinin kültivarlarıdır.

Çilekler, değerli C vitamini kaynağıdır.

Not: Bu metin http://tr.wikipedia.org/wiki/%C3%87ilek adresinden alınmıştır.

Gördüğünüz gibi, paragrafları göstermek için özel bir işaret kullanmıyoruz. Burada tek dikkat edeceğimiz şey her paragraf arasında bir boşluk bırakmaktır. Ayrıca başlığı yazdıktan sonra ilk paragrafı yazarken de, okunaklılık açısından başlıkla ilk paragraf arasında bir boşluk bırakmanızı tavsiye ederim.

Yukarıda verdiğimiz örneklerin html olarak nasıl göründüğünü test etmek için http://www.tele3.cz/jbar/rest/rest.html adresindeki çevrimiçi servisten, ya da Docutils paketi içinde yer alan rst2html adlı betikten yararlanabileceğinizi biliyorsunuz.

Yana yatık (italic) Metinler

rst metinlerinde kelimeleri yana yatık harflerle yazabilmek için yine “*” işaretinden yararlanacağız. Mesela şu örneğe bir bakalım:

*Python* kıvrak bir programlama dilidir.

Gördüğünüz gibi, “Python” kelimesini “*” işaretleri arasına aldık. Böylece bu kelime, mesela html’ye dönüştürüldüğünde yana yatık olarak görünecektir.

Kalın (bold) Metinler

Eğer bir paragraf içindeki herhangi bir kelimeyi kalın harflerle göstermek isterseniz yine “*” işaretinden yararlabilirsiniz. Ancak bu defa bu işareti çift olarak kullanacağız:

**Python** ve **Django** iyi bir ikilidir.

Bu metni html biçimine dönüştürdüğünüzde “Python” ve “Django” kelimelerinin kalın yazıldığını göreceksiniz.

Vurgulu Metinler

Eğer bir kelimeyi ve kelime grubunu, öteki kelimelerden farklı olarak vurgulu bir biçimde göstermek isterseniz “``” işaretinden yararlanabilirsiniz:

``Python`` ve ``Django`` iyi bir ikilidir.

Listeler

reStructuredText dilini kullanarak liste oluşturmak oldukça kolaydır. Biz bu bölümde listeleri “temel listeler” ve “özel listeler” olarak iki başlık altında inceleyeceğiz.

Temel Listeler

Temel listeler, sıkça kullanmamız gerekebilecek bilindik liste türleridir. “numaralı listeler” ve “numarasız listeler” bu sınıfa girer. Hemen ufak bir örnek verelim:

* Elma
* Armut
* Çilek
* Erik

Burada “*” işaretini kullanarak numarasız bir liste oluşturduk. İsterseniz “*” işareti yerine “+” veya “-” işaretlerini de kullanabilirsiniz. Liste oluştururken dikkat etmemiz gereken şey, işaret ile öğe arasında bir boşluk bırakmaktır. Yani mesela “*” işareti ile “Elma” öğesi arasında bir boşluk bıraktığımızdan emin olmalıyız.

Eğer amacımız numarasız listeler değil de numaralı listeler oluşturmaksa yine bunu çok basit bir şekilde halledebiliriz:

1. Elma
2. Armut
3. Çilek
4. Erik

Burada numaralı bir liste oluşturmak için sayılardan yararlandık. Aynı şekilde büyük ve küçük harfleri kullanmak da mümkündür:

A. Elma
B. Armut
C. Çilek
D. Erik

Veya:

a. Elma
b. Armut
c. Çilek
d. Erik

Hatta:

i. Elma
ii. Armut
iii. Çilek
iv. Erik

Dikkat ederseniz yukarıda numaralandırma işaretlerinin sağına birer adet nokta koyduk. Siz isterseniz nokta yerine “(” veya “()” işaretlerini de kullanabilirsiniz:

1) Elma
2) Armut

Veya:

(1) Elma
(2) Armut

reStructuredText ile numaralı liste oluşturmanın bir yolu da “#.” işaretlerini kullanmaktır:

#. Elma
#. Armut
#. Çilek
#. Erik

Yukarıdaki rst kodlarının çıktısı şöyle olacaktır:

1. Elma
2. Armut
3. Çilek
4. Erik

Yukarıda gösterilen numaralı ve numarasız listelerin yanısıra, dilerseniz tanım listeleri de oluşturabilirsiniz. Tanım listesinin ne olduğunu isterseniz bir örnekle görmeye çalışalım:

Ubuntu
    Debian tabanlı bir GNU/Linux dağıtımıdır

Mint
    Ubuntu tabanlı bir GNU/Linux dağıtımıdır

Windows
    Microsoft firmasının, özgür olmayan bir ürünüdür

Sanırım bu örnek “tanım listesi”nin ne demek olduğunu açıklıyor... Bazı çalışmalarınızda bu liste türünün oldukça işinize yaradığını göreceksiniz. Bu arada, yukarıdaki listedeki başlıkların kalın olması isterseniz bu örneği şöyle de yazabilirsiniz:

**Ubuntu**
    Debian tabanlı bir GNU/Linux dağıtımıdır

**Mint**
    Ubuntu tabanlı bir GNU/Linux dağıtımıdır

**Windows**
    Microsoft firmasının, özgür olmayan bir ürünüdür

Özel Listeler

Bu liste türü, adından da anlaşılacağı gibi, özel bir amaca hizmet eder. Mesela bir programın kullanım kılavuzu içinde gördüğümüz seçenek listeleri; program hakkında yazar, sürüm, lisans v.b bilgiler veren listeler hep bu sınıfa girer. İlk olarak seçenek listelerinden başlayalım. Mesela Python’u python -h komutuyla başlattığımızda çıkan seçenek listesinin bir bölümünü örnek olarak alalım:

-B        don't write .py[co] files on import; also PYTHONDONTWRITEBYTECODE=x
-c cmd    program passed in as string (terminates option list)
-d        debug output from parser; also PYTHONDEBUG=x
-E        ignore PYTHON* environment variables (such as PYTHONPATH)
-h        print this help message and exit (also --help)
-i        inspect interactively after running script; forces a prompt even
          if stdin does not appear to be a terminal; also PYTHONINSPECT=x
-m mod    run library module as a script (terminates option list)

Gördüğünüz gibi, seçenekleri ve bu seçeneklerin açıklamalarını, birbirlerinden boşluklarla ayırarak yerleştirdik. Eğer isterseniz seçenek tanımlarını alt satıra da alabilirsiniz:

-B
    don't write .py[co] files on import; also PYTHONDONTWRITEBYTECODE=x
-c cmd
    program passed in as string (terminates option list)
-d
    debug output from parser; also PYTHONDEBUG=x
-E
    ignore PYTHON* environment variables (such as PYTHONPATH)
-h
    print this help message and exit (also --help)
-i
    inspect interactively after running script; forces a prompt even
    if stdin does not appear to be a terminal; also PYTHONINSPECT=x
-m mod
    run library module as a script (terminates option list)

Burada seçenek açıklamalarını alt satıra aldıktan sonra, tanımı, ait olduğu seçeneğe göre girintili yazdığımıza dikkat edin. Bu yapı, özellikle uzun seçenek adlarının bulunduğu listelerde görünüş açısından tutarlılık elde etmenizi sağlayabilir.

Özel listeler kategorisinde değerlendirilebilecek bir başka liste türü de “künye listeleri”dir. Örneğin yazdığınız bir programda kullanıcılarınıza yazar adı, sürüm numarası, yayımlanma tarihi gibi künye bilgilerini derli toplu bir biçimde vermek isterseniz bu liste türünden yararlanabilirsiniz:

:Program Adı: HARMAN
:Yazarı: Fırat Özgül
:Sürüm: 0.8
:Dil: Türkçe, İngilizce

Köprüler/Bağlantılar

Yazdığınız belgelerin pek çok yerinde başka belgelere veya adreslere bağlantılar vermek isteyeceksiniz. Bu işlemi reStructuredText ile yapmak oldukça kolaydır.

Biz burada, bir metne farklı şekillerde nasıl bağlantı ekleyebileceğinizi göstereceğiz.

Doğrudan Bağlantı

Eğer metninize bir web sitesinin bağlantısını doğrudan eklemek isterseniz şu yöntemi kullanabilirsiniz:

Python, Guido Van Rossum adlı Hollandalı bir programcı tarafından yazılmış bir
programlama dilidir. Eğer Guido Van Rossum’un neye benzediğini merak ediyorsanız,
onun http://www.python.org/~guido/pics.html adresindeki fotoğraflarını inceleyebilirsiniz.

Gördüğünüz gibi, özel hiçbir işaret kullanmaya gerek olmadan, doğrudan web adresini metne ekleyerek amacımıza ulaşabiliyoruz. Yalnız reStructuredText biçimli metinlere bu şekilde bağlantı eklerken “http://” önekini yazmayı unutmuyoruz. Aksi halde bağlantı çalışmayacaktır...

Gizli Bağlantı

Bağlantıyı doğrudan görünür kılmak yerine bir kelime veya kelime grubunun altına da gizlemek isteyebilirsiniz. O zaman şöyle bir şey yazmanız gerekir:

Eğer Guido Van Rossum’un neye benzediğini merak ediyorsanız,
onun `şu <http://www.python.org/~guido/pics.html>`_ adresteki
fotoğraflarını inceleyebilirsiniz.

Burada şöyle bir yapı kullandık: `bağlantı metni <bağlantı adresi>`_. Bu yapıda kullanılan işaretlere çok dikkat ediyoruz. Formülde gördüğümüz ` işaretinin kesme işareti (‘) olmadığına da özellikle dikkat edin. Bu “çentik” işareti genellikle klavyede virgül işaretinin olduğu tuşun üzerindedir. Bu işareti üretmek için ALT + çentik tuşlarına basıyoruz. Bazı sistemlerde bu işareti çıkarabilmek için ALT + çentik tuşlarına art arda iki kez basmanız gerekebilir. Eğer bu şekilde iki adet çentik işareti oluşuyorsa birini silersiniz olur biter!..

Yukarıda gösterilen yöntem dışında, metin altına bağlantı eklemenin farklı yolları da vardır. Örneğin:

Arama yapmak için `tıklayınız`_

.. _tıklayınız: http://www.google.com

Veya daha basit bir şekilde:

Arama yapmak için `tıklayınız`__

__ http://www.google.com

Şu son iki örnek, görüntü açısından daha derli toplu reStructuredText metinleri hazırlamanıza yardımcı olabilir. Mesela içinde birden fazla bağlantı içeren paragrafları şu şekilde yazarak kendi açınızdan daha düzenli ve tertipli bir rst belgesi elde edebilirsiniz:

Bu konu ile ilgili daha ayrıntılı bilgilere `şuradan`__,
`şuradan`__ ve `şuradan`__ erişebilirsiniz.

Ayrıca bu konuya ilişkin çalışmalarınızda yukarıdakilerin
dışındaki kaynakları da incelemenizi tavsiye ederim.

__ http://www.google.com
__ http://www.yahoo.com
__ http://www.hotmail.com

Burada gördüğünüz gibi, “şuradan” kelimesi birden fazla kullanıldığında, kelimelerin yazılış sırası dikkate alınıyor.

reStructuredText metinlerinde bağlantı vermenin değişik yolları olsa da siz muhtemelen yukarıda verilen ilk iki yöntemi kullanmayı tercih edeceksiniz. Ancak elbette bu yöntemler içinde size en kolay gelen yöntemi seçmekte serbestsiniz...

Değişkenler

Bazen bir metin hazırlarken, özel bir kelime veya kelime grubunu değişken olarak kullanmak isteyebilirsiniz. Bunun şöyle bir faydası vardır: Diyelim ki yazdığınız metnin pek çok yerinde aynı web sitesine göndermede bulunuyorsunuz. Bu web sitesinin adresini her defasında elle yazmak yerine, bunu bir değişkene atayıp metin içindeki gerekli yerlerle kullanmak isteyebilirsiniz:

Bu konuda yazılmış en iyi kaynak |web sitesi| adresinde bulunur.
Ancak |web sitesi| adresinden yararlanabilmek için bu siteye üye
olmanız gerekmektedir.

|web sitesi| sitesinin sahipleri, inceleme yaptığınız konuda
size ellerinden geldiğince yardımcı olmaya çalışacaklardır.

.. |web sitesi| replace:: http://www.falanca.com

Burada replace adlı özel bir ifadeden yararlandığımıza dikkat edin. Ayrıca kullanılan öteki işaretlere de özellikle dikkatinizi çekmek isterim. Bu yöntemin, işlerinizi ne kadar kolaylaştıracağını tahmin edebilirsiniz. Yukarıdaki metinde geçen www.falanca.com adresini sadece tek bir yerde değiştirerek, bu değişikliğin bütün metne uygulanmasını sağlayabilirsiniz.

Yukarıdaki gibi, metin değişkenleri kullanabilmenin yanısıra, reStructuredText bize resimleri de aynı şekilde kullanma imkanı sağlar. Bunun için replace yerine image adlı bir ifadeden yararlanacağız:

|dikkat| simgesi, programı kullanırken dikkat etmeniz
gereken şeyleri gösterir.

.. |dikkat| image:: dikkat.jpg

Kod Alanları

reStructuredText’i kod içeren belgeleri hazırlamak için kullanacağınızı düşünürek, işinize bir hayli yarayacak bir özellikten bahsetmemizde yarar var. Şu örneğe bir bakalım:

Tkinter kullanarak yazılabilecek örnek bir program şöyle olabilir::

    #-*-coding: utf-8 -*-
    from Tkinter import*

    class Uygulama(object):

        def __init__(self):
            self.gui_pen_ar()

        def gui_pen_ar(self):
            self.label = Label(text = "Programımıza hoşgeldiniz...")
            self.label["bg"] = "light yellow"
            self.label["font"] = "helvetica 15 bold"
            self.label["relief"] = GROOVE
            self.label.pack(pady = 10, padx = 10)


            for k, v in [("Tamam", None), ("Çık", pencere.quit)]:
                self.btn = Button()
                self.btn["text"] = k
                self.btn["command"] = v
                self.btn["width"] = 10
                self.btn["font"] = "verdana 13 italic"
                self.btn["relief"] = RIDGE
                self.btn.pack(side = LEFT,
                              padx = 20,
                              pady = 20)

    pencere = Tk()
    uyg = Uygulama()
    pencere.title("Merhaba")
    pencere.mainloop()

Eğer yukarıdaki örneği rst2html betiği yardımıyla HTML’ye dönüştürecek olursanız, kod alanının metnin geri kalanından şık bir şekilde ayrıldığını ve gri bir arkaplan rengiyle gösterildiğini göreceksiniz. İlerde Sphinx yazılımını kullandığımız zaman buradaki kodların daha zarif bir şekilde renklendiğine de şahit olacağız...

Burada dikkat etmemiz gereken en önemli şey kod bloğunun başlayacağını gösteren :: işaretidir. Tkinter kullanarak yazılabilecek örnek bir program şöyle olabilir cümlesinin ardından :: işaretini koyarak alt satıra geçtikten sonra kodlarımızı girintili olarak yazıyoruz. Buradaki :: işareti, HTML çıktısında cümle sonuna bir adet de iki nokta üst üste işareti yerleştirecektir. Eğer siz iki nokta üst üste işareti yerine mesela noktalı virgül koymak isterseniz ilk cümleyi şöyle yazabilirsiniz:

Tkinter kullanarak yazılabilecek örnek bir program şöyle olabilir; ::

Burada “;” işaretinden sonra getirdiğimiz “::” işaretini noktalı virgülden ayrı yazdığımıza dikkat edin. Ayrıca bu cümleyi yazdıktan sonra, kodlarımızı yazmaya başlamadan önce bir satır boşluk bırakmayı da unutmuyoruz...

Dipnotları

Yazdığınız metinlere dipnotlarını eklemek için şöyle bir yol izleyebilirsiniz:

2009 yılına ait verilere göre [#]_ Python programlama dili yükseliştedir.

.. [#] http://www.falanca.com

Eğer dipnotlarını elle numaralandırmak isterseniz yukarıdaki kodları şöyle yazmanız gerekir:

2009 yılına ait verilere göre [2]_ Python programlama dili yükseliştedir.

.. [2] http://www.falanca.com

Resimler

Yazdığınız metinlerde resim gösterebilmek için şöyle bir yapıdan faydalanıyoruz:

.. image:: resim.jpeg

Eğer arzu ederseniz resmin ekranda nasıl görüneceğini belirlemek için bazı seçeneklerden de yararlanabilirsiniz:

:height: 100px
:width: 200 px
:scale: 50 %
:alt: resmi tanımlayan bir metin
:align: right

Burada “height” resmin boyunu, “width” resmin enini, “scale” resmin ölçeğini, “alt” resmi tanımlayan bir metni, “align” ise resmin ne tarafa hizalanacağını gösteriyor. Eğer resminizi sağa yaslamak isterseniz :align: değerini “right”, sola yaslamak isterseniz “left”, ortalamak isterseniz “center” şeklinde belirleyebilirsiniz. Sonuç olarak, bir metin içindeki resmi göstermek için şu biçimi kullanıyoruz:

.. image:: picture.jpeg
   :height: 100px
   :width: 200 px
   :scale: 50 %
   :alt: resmi tanımlayan bir metin
   :align: right

Burada elbette bütün seçenekleri kullanmak zorunda değilsiniz. İsterseniz varsayılan değerleri de kabul edebilirsiniz.

Yorumlar

Eğer yazdığınız metinlere yorum eklemek isterseniz şöyle yapmanız gerekir:

..
    Bu bir yorumdur.
    Bu da bir yorumdur.
    Bu da...

.. işaretinden sonra alt satırda girintili olarak gösterdiğiniz her şey bir yorum olarak değerlendirilecek, mesela HTML çıktısında görünmeyecektir.

Böylece Sphinx adlı yazılımı rahatlıkla kullanmamızı sağlayacak kadar reStructuredText bilgisi edinmiş olduk. Şimdi gönül rahatlığıyla Sphinx’i anlatmaya başlayabiliriz.

Alıntılar

Hazırladığınız belgelerde başka bir yazardan veya metinden alıntı yapmak isterseniz şöyle bir yapı kullanabilirsiniz:

Ana paragraf buradan başlıyor. Hemen altta ise
alıntı bir metin yer alıyor.

    Alıntı metin burada başlıyor.
    Alıntı metnin devamı...

Alıntı metin sona erdi. Artık ana paragraftayız.

Yukarıdaki rst metninin HMTL çıktısı ise şöyle olacaktır:

Ana paragraf buradan başlıyor. Hemen altta ise alıntı bir metin yer alıyor.

Alıntı metin burada başlıyor. Alıntı metnin devamı...

Alıntı metin sona erdi. Artık ana paragraftayız.

Tablolar

reStructuredText’in en zor, daha doğrusu en sıkıcı yanlarından birisi de tablo oluşturmaktır. Yazacağımız belgelere bir tablo eklemek için tabloyu elle çizmemiz gerekiyor!

+----------+----------+----------+----------+
| İSİM     | SOYİSİM  | ADRES    | MESLEK   |
+==========+==========+==========+==========+
| Ferhat   | Gider    | İstanbul | Yazar    |
+----------+----------+----------+----------+
| Ahmet    | Erden    | Ankara   | Çevirmen |
+----------+----------+----------+----------+
| Mehmet   | Artır    | İzmir    | Çizer    |
+----------+----------+----------+----------+
| Kezban   | Güler    | Adana    | Mühendis |
+----------+----------+----------+----------+
| Selin    | Güleç    | Bursa    | Öğretmen |
+----------+----------+----------+----------+
| Selim    | Gelir    | İzmit    | Esnaf    |
+----------+----------+----------+----------+

Bu çizim, HTML’ye dönüştürüldüğünde şöyle bir çıktı verecektir:

İSİM	SOYİSİM	ADRES	MESLEK
Ferhat	Gider	İstanbul	Yazar
Ahmet	Erden	Ankara	Çevirmen
Mehmet	Artır	İzmir	Çizer
Kezban	Güler	Adana	Mühendis
Selin	Güleç	Bursa	Öğretmen
Selim	Gelir	İzmit	Esnaf

Yukarıdaki tabloda, istediğiniz görünümü elde etmek için çizgilerin yerlerini değiştirebilir veya gereksiz gördüğünüz çizgileri silebilirsiniz.

reStructuredText biçimli belgelerde yukarıdaki gibi tabloları daha zahmetsiz bir biçimde oluşturmak isterseniz rstab modülü‘nden yararlanabilirsiniz.