Ziyaretci:4675
Ö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.
