Evet Software Tech
Published in

Evet Software Tech

Read the Docs(Sphinx) — Türkçe Kaynak

Bir önceki makalemizde Kaynak Kod Dokümantasyonu sürecini ele almıştık. Bu süreç içerisinde projelerimizin iş akışını geliştiriciye anlattığımız veya çalışma mantığını son kullanıcılara anlattığımız teknik (belge)dokümanlar hazırlama ihtiyacımız doğdu. Bu noktada Read the Docs ile yollarımız kesişti.

Read the Docs açık kaynak kodlu ve ücretsiz bir platform olup bize hızlı ve olabildiğince basit bir şekilde teknik dokümanlar oluşturabileceğimiz güçlü bir alt yapı sunuyor.

Read the Docs bizim için Sphinx Documentation Generator ile yazılımış dokümanlar oluşturmamızı sağlar. Sphinx, Python topluluğu tarafından oluşturulmuştur.

Sphinx ile web sayfaları, PDFler, e-Publar ve birçok farklı formatta dokümanlar oluşturabilirsiniz.

Detaylı teori bilgi için dokümantasyonun linkini buraya bırakıyorum.

Kurulum ve Hello World!

İlk iş olarak makinamıza Python kurulumunu gerçekleştiriyoruz.

Not : Add Python x.x to PATH ifadesini işaretlemeyi unutmayın.

Python kurulumu sonrasında sphinx kurulumu için aşağıdaki kod satırını komut satırı üzerinden çalıştırıyoruz.

$ pip install sphinx

Kurulumlar esnasında bir hata ile karşılaşmadıysanız eğer kurulum işlemlerimiz burada tamamlanıyor.

Bulunduğumuz noktada bir Sphinx projesini ayağa kaldırıp sonrasında dünyayı selamlama geleneğimizi sürdürmek adına hiçbir engel kalmadığını görüyorum.

$ sphinx-quickstart

Yukarıdaki komut ile hızlı kurulum yapıyoruz. Kurulum esnasında;

Project name, Author name(s), Project language gibi bir takım sorular ile karşılaşıyoruz; bu alanları doldurarak projemizi ayağa kaldırıyoruz. Başlangıçta emin olmadığınız alanları boşluk bırakarak devam edebilirsiniz. Projemiz ayağa kalktıktan sonra bu bilgileri ufak birkaç kurcalamayla düzenleme şansına sahip olacağız.

Proje dosyalarımız

Projemizi oluşturduğumuza göre /source yolu altında bulunan index.rst dosyamızda ufak bir “Hello World!” eklemesi yapalım ve projemizi ayağa kaldıralım.

$ ./make html

Projemizi ayağa kaldırmadan önce yukarıdaki komutumuzu çalıştırıyoruz. Bu işlem sonrasında /build yolu altında doctrees ve html adında iki tane klasörümüzün oluştuğunu görüyoruz.

/Html klasörü altında bulunan index.html dosyasını çalıştıralım.

Eğer aşağıdakine benzer bir görüntüyü sizler de görüyorsanız her şey yolunda demektir.

Dokümanımızı incelediğimiz zaman bizim sonradan eklediğimiz “Hello World!” ve bizden kurulum esnasında istenen Project name ve Author name bilgilerinin de barındığı alabaster teması ile bizleri karşılıyor.

Geliştirme esnasında bize yardımcı bir eklenti olan reStructuredText’in linkini buraya bırakıyorum.

Tema Düzenleme

Proje dosyalarımızı bir ufak göz attıysanız eğer bizi index.rstconf.py gibi birkaç temel proje dosyasının karşıladığını görüyoruz. index.rst dosyamız bizim layoutumuz ve conf.py ise yapılandırma dosyası olduğunu göreceksiniz.

Önce Sphinx Theme’mızı kuralım ve yapılandırma dosyamıza bu temayı kullanmak istediğimizi belirtelim.

$ pip install sphinx-rtd-theme
$ ./make html

Yukarıdaki komutumuz yardımıyla projemizi yeniden derleyerek ayağa kaldırabilir veya ctrl + k ve ctrl + r komutlarıyla veya ekranın sağ üst köşesinde bulunan preview düğmesiyle de değişikliklerimizi gözlemleyebiliriz.

Ve Sphinx-rtd temamız:

Buraya incelemeniz için Read the Docs(Sphinx) ile geliştirilmiş olan Automapper dokümantasyonunu bırakıyorum.

https://docs.automapper.org/en/stable/Getting-started.html

TOCTREE (Menü Ağaç Yapısı)

Örnek Menü Ağaç Yapısı

Örnek resimdeki menü ağaç yapısını oluşturmak için;

source/options altına .rst uzantılı bir dosya oluşturuyoruz (Burada da bu oluşturduğumuz dosyaları partial view yapısına benzetebiliriz diye düşünüyorum.) ve index.rst daha önce layout yapısına benzettiğimiz sayfamıza gelip bu sayfalarımızın tanımlamasını yapıyoruz.

Şimdi de bu noktadaki hedefimiz olan ağaç yapısını oluşturacak olan kodlarımızı yazalım.

Örnek kodlamayı inceleyerek işlerin ne kadar kolay ve akılda kalıcı yürüdüğünü fark etmişsinizdir.

Oluşturduğumuz menü ağaç yapımızın ana sayfadan gizlemek istersek .. toctree:: içerisine aşağıdaki :hidden: ifadesini ekleyebilirsiniz.

İçerik Düzenleme

Liste

Uyarılar

Resim

Projemizde bir resim göstermek için source/images altına resimlerimizi ekledikten sonra aşağıda gördüğünüz kod satırıyla da resmimizi göstermiş oluyoruz.

Kod Embed

Öncelikle örnek kod bloğunu gösterebilmemiz için conf.py içerisine aşağıdaki kodu ekliyoruz ve ilgili sayfamızda da kodlamamızı yapıyoruz.

highlight_language = 'csharp'

Tablo

Tablo oluşturmanın birçok farklı yolu mevcut. Örnek olarak buraya birkaç tanesini bırakıyorum.

İkinci bir yaklaşım ise;

Link

Bu noktaya kadar yaptıklarımızı bir özet geçecek olursak eğer kurulum, metin düzenleme, resim ekleme, kod embed, tablolar gibi birçok örnek uygulama göstermeye çalıştım.

Hata durumlarında output ve öncelikle gözden geçirmenizi düşündüğüm kısım eğer flutter ile uygulama geliştirdiyseniz benzer bir duruma zaten aşinasınızdır diye düşünüyorum. Boşluklar dikkat etmelisiniz.

Ufak bir tekrara düşmek gerekirse; son iki makalemde hepimizin muhakkak fikir sahibi olduğu fakat bir çoğumuzun uygulamadığı/uygulayamadığını düşündüğüm kaynak kod dokümantasyonu konusunu ve projelerimizin iş akışlarını geliştiriciye ve çalışma mantığını son kullanıcıya anlatacağımız teknik belgeler oluşturma konularını inceledik.

Dokümantasyon konusunda devam edeceğimiz makale serimizin üçüncü bölümünde projemizi Github hesabımıza yüklemeyi ve Read the Docs ile webhook üzerinden bağlama işlemlerini gerçekleştireceğiz. Böylelikle belirleyeceğimiz şartlar özelinde ekip arkadaşlarımız veya açık kaynak projeler özelinde herhangi bir kullanıcının bizim oluşturduğumuz dokümanlara geliştirme amaçlı pull requestler gönderebilecekleri bir geliştirme sunmaya çalışacağım.

Devam edeceğiz…

--

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Mustafa Dikyar

Mustafa Dikyar

Software Developer

More from Medium

Viafoura Conversations — Making Custom User Badges using Python

The date command is used to display the system date and time.

Just a simple Makefile to avoid to repeat yourself

Automated SFTP with PGP encryption and decryption

cloud managed file transfer pgp