Python’ın resmi dökümantasyonu, birçok kütüphane sphinx kullanılarak bir belge haline getiriliyor. Siz de ders notlarınızı veya hazırladığınız belgeleri Sphinx kullanarak pdf veya html formatına dönüştürebilirsiniz.
İsterseniz adım adım gidelim.
Öncelikle sphinx’i bilgisayarınıza nasıl yükleyebilirsiniz onu anlatmaya çalışayım:
1. Sphinx Kurulumu
1.1. Windows İçin:
Sphinx’i Windows’a pip’i kullanarak kurabiliriz.
pip3 install sphinx
Artık sphinx’i html belgesi oluşturmak için kullanabiliriz ancak bir pdf dosyası oluşturmak için sistemimize yüklememiz gereken programlar var hala. latexmk bu programlardan birisi. Hemen latexmk’nın dökümantasyonunda Windows için kurulumun nasıl olduğuna bakalım.
Latexmk Dökümantasyonu: Using Latexmk — homepage
Bu dökümantasyonda şöyle bir paragraf var:
On Windows with MikTeX:
You probably have to install Perl, e.g. from here: http://strawberryperl.com/. If it’s not installed already, open the MikTeX Package Manager and install the latexmk package.
Yukarıdaki alıntıda özetle latexmk’yı MikTeX ile birlikte kurabileceğimiz ve aynı zamanda Perl’ün de sisteme kurulmasının gerekebileceği yazıyor. Ayrıca paragrafın son satırında belirttiğine göre latexmk’yı, MikTex’in paket yöneticisi ile kurabileceğimiz söyleniyor.
O halde önce MikTex’i indirelim.
İndirme Sayfası: Getting MiKTeX
Bu adresten basic-miktex-2.9.7152-x64.exe dosyasını bilgisayara indiriyorum. Kurulumunu yapıyorum. Kurulum bittikten sonra MikTex Console isimli bir uygulamanın açılması lazım. Eğer uygulama güncellenmesi gereken dosyalar olduğu yönünde bir bildirimde bulunuyorsa o dosyaları güncelleyin.
Daha sonra Packages isimli düğmeye tıklayın. Şöyle bir ekran görmeniz gerekiyor.
Buradaki veri girişi yerine latexmk yazıp enter tuşuna basınca latexmk karşınıza gelecektir.
Bu resimde gördüğünüz gibi Install package seçeneğine tıklayarak, sisteminize latexmk’yı kurabilirsiniz. Paylaştığım ekran görüntüsünde latexmk daha önce sisteme kurulmuş olduğu için bu seçenek iptal edilmiş görünüyor. Ama sizinkinde bu seçenek kullanılabilir olacaktır.
MikTex’i kurduk. Şimdi sıra geldi perl’ü kurmaya. Kullandığım Windows mimarisi 64-bit olduğu için 64-bit sürümü indiriyorum.
64-bit: http://strawberryperl.com/download/5.30.0.1/strawberry-perl-5.30.0.1-64bit.msi
32-bit: http://strawberryperl.com/download/5.30.0.1/strawberry-perl-5.30.0.1-32bit.msi
Perl’ü de bilgisayara kurduktan sonra artık sphinx kullanarak pdf dosyaları oluşturabiliriz.
1.2. Linux İçin:
Linux’e sphinx, Windows’a kurulduğundan daha zahmetsiz bir şekilde kurulur. Öncelikle yine pip ile sphinx modülünü kuruyoruz.
pip3 install sphinx
Daha sonra pdf oluşturabilmek için latexmk’yı kuruyoruz.
sudo apt install latexmk
Daha sonra ise aşağıdaki paketi kuruyoruz.
sudo apt install texlive-formats-extra
Ve Linux’te de artık belgelerimizi pdf dosyası olarak oluşturabiliriz.
2. Sphinx Kullanımı
Proje dosyalarımızı deneme isimli bir klasörde tutalım. Bu klasörde de konsol ekranını açalım.
Sphinx’i kullanmak için konsol ekranına aşağıdaki komutu yazıyoruz.
sphinx-quickstart
Komutu yazdıktan sonra sphinx bizden oluşturulacak belgeyle alakalı bir takım bilgiler girmemizi ister. Bu seçeneklerden ilki aşağıdaki gibidir:
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]:
Burada, sphinx bize iki ayrı seçenek sunar. Seçeneklerden birisi source ve build isimli iki tane klasörü oluşturur. Bunun için y tuşuna basmak gerekir. Bir diğer seçenek ise _build isimli bir klasörün oluşturulmasını sağlar ve bu seçeneği seçmek için sadece enter tuşuna basmanız yeterlidir.
Bir sonraki sphinx sorusu ise aşağıdaki gibidir:
The project name will occur in several places in the built documentation.
> Project name:
Anlaşılacağı üzere burada sphinx bizden projenin ismini belirlememizi istiyor. Herhangi bir isim yazıyoruz buraya.
Daha sonra sphinx bizden belgeyi hazırlayanın kişi veya kişilerin isimlerini yazmamızı ister.
> Author name(s):
Buraya da herhangi bir isim yazıyoruz ve enter tuşuna basıyoruz.
Bir sonraki sphinx sorusu ise, bu hazırlanacak belgenin sürümünün ne olacağıyla ilgilidir.
> Project release []:
Buraya v1.0 gibi bir sürüm numarası yazabiliriz.
Sonraki sphinx sorusu ise belgenin dilinin ne olacağı ile alakalıdır. Ön-tanımlı olarak bu değer en’dir. Eğer biz Türkçe bir belge oluşturmak istiyorsak, soruya tr cevabını verip enter tuşuna basmamız gerekiyor.
If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.
For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]:
Bu kısma da tr yazdıktan sonra sphinx sonradan derlenecek olan belge projesi dosyalarımızı oluşturur.
deneme isimli klasörümüzün içinde aşağıdaki dosyaların oluşmuş olması lazım.
deneme+
|_build+
|_static+
|_templates+
|conf.py
|index.rst
|make.bat
|MakeFile
Buradaki index.rst dosyasını birazdan belge oluştururken, oluşturduğumuz belgelerin isimlerini belirtmek ve aynı zamanda belgemize bir İçindekiler hızlı dizini eklemek için kullanacağız.
Ama önce bu index.rst dosyasının içine bakalım. Aşağıdakilerin içinde yazılı olması gerekiyor.
.. a documentation master file, created by
sphinx-quickstart on Fri Aug 23 17:09:59 2019.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to a's documentation!
=============================
.. toctree::
:maxdepth: 2
:caption: Contents:
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
Şimdi burada bilmeniz gereken bazı hususlar var. Örneğin .. toctree:: ifadesi, özel bir anlama gelir ve dökümanımızın ağaç görünümünde olmasını sağlar. Bu ifadenin gördüğünüz gibi kendi argümanları var. Mesela :maxdepth: 2 gibi. Bunların hepsi belgenin özelliklerini değiştiren parametreler. Mesela :maxdepth: 2 parametresi, belgedeki ağaç görünümünün 2. girintiye kadar gösterilmesini sağlar.
Şimdi bu index.rst dosyasının içeriğini şu şekilde değiştiriyorum:
.. toctree::
:maxdepth: 2
:caption: Contents:
İçinde şuanlık sadece bunlar olsun.
Şimdi gelin yeni bir tane rst dosyası oluşturalım. Ve bu dosyanın içine bir şeyler yazalım.
Dosyanın ismini sayfa1.rst olarak belirledim. Tabi bu belgede anlatacağımız konuyla alakalı bir isim de verebiliriz.
sayfa1.rst dosyasının içine şunları yazalım.
Örnek-1:
--------
Aşağıdaki python kodunu çalıştırınız::
print("hello world")
Örnek-2:
--------
Aşağıdaki python kodunu çalıştırınız::
print(range(10))
Dikkatinizi çekmiştir herhalde, python kodlarını yazmadan önce :: işaretlerini normal metnin sonuna yerleştirdik, daha sonra ise bir satır boşluk bıraktık ve Python kodlarını 4 karakterlik bir girinti kullanarak yazdık.
Dosyayı kaydedelim ve şimdi index.rst dosyamıza bu belgeyi ekleyelim.
index.rst’yi açıyoruz ve sayfa1’i aşağıda gösterildiği gibi ekliyoruz.
.. toctree::
:maxdepth: 2
:caption: Contents:
sayfa1
Şimdi isterseniz, konsola make html yazıp, belgemiz nasıl görünüyor bir bakalım.
make html
Her şey yolunda giderse hiç bir hata mesajı almayız. Html dosyalarımız /deneme/_build/html klasörünün içinde yer alır. Buradaki index.html sayfasını internet tarayıcısı ile açıyorum. Ve şöyle bir çevrimdışı web sayfası açılıyor.
Bu web sayfasındaki Örnek-1 linkine tıklıyorum.
Evet gördüğünüz gibi, dökümanımız yavaş yavaş oluşmaya başlamış. Dilerseniz, htm sayfasını kendi zevkinize göre dizayn edebilirsiniz. Bazen dökümana bir resim dosyası veya bir video dosyası eklemek isteyebilirsiniz veya html dosyasına css ile stil kazandırmak isteyebilirsiniz veya otomatik olarak oluşturulan bazı yazıların gözükmemesini sağlayabilirsiniz veya belki javascript ile html dosyasını daha fazla özellik eklemek isteyebilirsiniz. Bunların hepsi sizin isteğinize bağlı.
index.rst dosyasında şöyle bir ifade vardı:
:caption: Contents:
Bu ifadedeki Contents sözcüğü yerine İçindekiler yazarsanız, html dosyasındaki Contents yazısının yerine İçindekiler yazısı yazılır.
Şimdi gelin make latexpdf komutu ile bir pdf dosyası oluşturalım.
make latexpdf
Ekran görüntüsünü de paylaşayım.
Ancak bu pdf dosyası tam istediğim gibi çıkmadı. Yani link sıralamasında bir hata var. Bunu şu şekilde çözebiliriz. sayfa1.rst’yi aşağıdaki gibi değiştiriyoruz.
********
Örnekler
********
Örnek-1:
--------
Aşağıdaki python kodunu çalıştırınız::
print("hello world")
Örnek-2:
--------
Aşağıdaki python kodunu çalıştırınız::
print(range(10))
Ve tekrar make latexpdf komutunu çalıştırırsak, Örnek-1 ve Örnek-2 görünecek ancak Örnekler görünmeyecektir. Yani belgeye önce başlığını vermemiz gerekiyor.
Ekran görüntüsüne bakalım.
Evet, gördüğünüz gibi bu sefer Örnek-1’i yer imlerinde görebiliyoruz.
sphinx ile hem html hem de pdf dosyası oluşturmak mümkün. Burada basit örnekler göstererek konuyu anlatmaya çalıştım. Bir de rst dosyalarında kullanılan .. toctree:: gibi bazı özel işlemleri yapan ifadeler var. Bunları öğrendiğimiz taktirde, belge içeriğini daha da zenginleştirebiliriz. Aşağıdaki siteden bu özel ifadelerden bazılarının ne olduğunu ve ne işe yaradığını inceleyebilirsiniz.