Yazılım Geliştirmede Dökümantasyon

Öncelikle bu yazıya başlamadan beni bu konuda bilinçlendiren iki insana teşekkür etmek istiyorum.İlker manap ve Nikos Efthias hocalarıma teşekkür etmek istiyorum.

DÖKÜMANTASYON NEDİR ?

Dökümantasyon, düşünce ürünü olan bütün bilgileri toplama, sınıflama ve kolayca yararlanmaya sunulacak biçimde saklama işlemi; bilimsel haberleşmenin en büyük hız ve doğrulukla gerçekleşebilmesi için yapılan işlemlerin tümü.

NEDEN  DÖKÜMANTASYON HAZIRLANIR ?

Kısacası eğer bir geliştirme ekibinde veya açık kaynak bir uygulama geliştiriyor isek ürettiğimiz  yazılımı başka kullanıcı ve geliştiriciler için daha anlaşılabilir hale getiriyor.Bir senaryo oluşturalım,siz birkaç kişi ile birlikte bir yazılım geliştiriyorsunuz ancak yapılan işlemleri daha anlaşılır hale getirmek için dökümantasyon hazırlamak projeyi daha anlaşılabilir hale getirir.
Örnek dökümantasyon  olarak  https://golang.org/doc/, https://docs.couchdb.org/en/stable/ websitelerini inceleyebilirsiniz.

DÖKÜMANTASYON ARAÇLARI

Gelelim kuru fasulyenin faydalarına ,lafı uzatmadan 3 araç tanıtalım.Sphinx(python),Jsdoc(javascript),doxygen(çoklu dil desteği) dilleri için oluşturulmuş ,döküman oluşturan araçları  tanıtalım.

SPHİNX İLE DÖKÜMAN OLUŞTURMAK

Python severler için basit bir proje oluşturup ve bu projenin dökümantasyonunu hazırlayalım.Not sphinx indirmek için sphinx’in resmi websitene buradan ulaşabilirsiniz.https://www.sphinx-doc.org/en/master/
Eğer linux kullanıyorsanız ,’sudo apt-get install sphinx’ veya ‘pip install -U sphinx’ yazarak (eğer pip kullanıyorsanız) zaten indirilecektir.

SPHİNX

Dosya yapımızı oluşturalım.

‘sphinx-quickstart’ yazarak dökümanımızı oluşturalım.Birkaç soruyu yanıtlayalım ve dökümantasyon dosyamızı açalım.
rst klasörü içerisine sayfaları oluşturacağımız için klasörü açtım.
                                                                                                                                                                                                                                                                                                 Şimdi ise configurasyon dosyamızı düzenleyelim.
Şimdi ise sourcecode içerisine düzenlemek istediğimiz python scriptini yorum satırları ile inceleyelim.Dosyaya buradan ulaşabilirsiniz -https://gist.github.com/SirmaXX/8e3658949b110fc7c2996e11c1bb86f3
                                             Ardından docs dosyasının içine girelim .’sphinx-apidoc -o rst sourcecode’
‘rst/modules’ yazısını ekleyelim ,çünkü rst klasörü içerisindeki rst dosyalarındaki dökümanları aktarmak için gerekli bir işlem.
make html yazıp ardından build/html klasörüne girelim.
index.html dosyasını açalım.Dökümanımız hazır 🙂

JSDOC

Şimdi ise hazırladığım eski bir projeye jsdoc ile bir dökümantasyon edelim.https://github.com/SirmaXX/flipflopprinter buradan bu repoya ulaşabilirsiniz.Şimdi ise jsdocu indirelim  ‘sudo npm install -g jsdoc’ yazarak indirebiliriz.
Yorumları satırlanı jsdoc’a uygun yazalım
.
‘sudo jsdoc options.js -d docs’ yazarak option.js için bir dökümantasyon oluşturalım.Ardından docs klasörü içerisinde index.html dosyasına girelim.
Dökümantasyon hazır .

DOXYGEN

Aslında sadece doxygen kullanmakta yeterli birçok dil desteğine sahip bir dökümantasyon oluşturma aracıdır.Örnek olması açısından hazır bir projeye dökümantasyon ekleyelim. https://github.com/SirmaXX/cpp_examples/tree/master/SpaceLand buradan ulaşabilirsiniz.
‘sudo apt-get install doxygen’ yazarak veya http://www.doxygen.nl/download.html buradan indirebilirsiniz.
Dosya yapımızı oluşturup,docs klasörünü açıp, ‘doxygen -g’ yazıp Doxyfile oluşturulsun.
docs klasörünün içini açıp ,doxyfile dosyasını editleyelim.
PROJECT_NAME = <proje ismi>
 INPUT=<dosya yolu>
 GENERATE_LATEX=no “latex oluşturmak isterseniz yes yazın”
 GENERATE_LATEX=yes   olarak  konfigurasyon dosyamızı oluşturalım.
Not: Burada istediğimiz ayarları düzenleyebiliriz.
                                     Yorum satırlarınıda ekleyelim .
                              Dosyamızı kaydedip docs klasörüne gelip ‘doxygen DOXYFILE’ yazıp dökümantasyonu oluşturalım.
Dökümantasyonumuz hazır.

Bir cevap yazın

E-posta hesabınız yayımlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir