Docfx - .NET Projeleri için Dokümantasyon Aracı

Docfx, teknik doküman sitesi oluşturmak için .NET topluluğunun desteklediği açık kaynaklı bir projedir. Docfx - Github Pages


Geliştirilen .NET projelerinde bulunan assembly yapısını, Xml tabanlı yorum satırlarını, Swagger dosyası ve markdown dosyalarını; Html veya pdf formatına dönüştürülmesini sağlar.

Faydaları;

  • Ekiplerinize projedeki bileşenleri (sınıf, metot) kod bloklarına boğulmadan görsel bir çıktı vermek için kullanışlıdır. 
  • Summary blokları kod seviyesinde kaldığı için yazılımcı olmayan birinin anlaması zordur.
  • Ekip üyelerinin yapılan işler sırasındaki dokümantasyon sürecine teşvik eder. 
  • Link desteği sayesinde, metodun bağlı olduğu bileşene ulaşılabilir. 
  • Ekibe yeni katılan bir kişinin projeye hızlı uyum sağlamasını kolaylaştırır.

Web sitesinin kurulum aşamaları

Eğer .NET SDK varsa, komut satırını kullanarak aşağıdaki komut çalıştırılır. Çalıştırılan bu komutla, dotnet CLI aracılığıyla docfx aracını yükler. 

dotnet tool install -g docfx
Kurulum tamamlandığında aşağıdaki gibi başarılı mesajını görebilirsiniz.


Örnek bir dotnet projesinde dokümante etmek istenilen projeler, src klasörünün içerisinde bulunuyor. 
Dokümantasyon sitesi için docfx_site adında bir klasör oluşturuldu.

src klasöründe iki adet proje bulunmakta olup; Core katmanı için Class library ve Web Api projeleridir. Projeler .NET 8 sürümünde geliştirilmiştir.


Çalışılan projenin bulunduğu klasörde komut istemcisini açıp, aşağıdaki komutu yazarak docfx projesi oluşturmak için başlangıç yapabiliriz.
docfx init
Bu komutu girdikten sonra yapılandırma ayarları için aşağıdaki sorulara cevap vermek gerekir.


Name: Web sitesinin ismi ve aşağıdaki gibi görünecektir. Değer girilmezse mysite olacaktır.


Generate .NET API documentation?: Dokümantasyon için Y - Yes denilmelidir.
.NET Projects location: csproj uzantılı dosyaların bulunduğu klasörün konumudur. Değer girilmezse varsayılan olarak src klasöründe olduğunu kabul eder ve klasör yoksa csproj dosyası olmadığı için istenilen sonucu vermeyecektir.

Örneğimde; src klasörü oluşturdum fakat konumu gereği ./ ile bir üst dizine konumu verdim. 

Markdown docs location: md uzantılı dosya oluşturup ana sayfada gösterilecek markdown dosyalarının klasör yolunu veriririz. Github readme dosyalarının formatı olan bu dosyalar varsayılan olarak aşağıdaki şekilde görünecektir. Değer girilmezse varsayılan olarak docs klasörü oluşturur.

getting-started markdown içeriği

Dokümantasyon sitesindeki menüde Docs sekmesi altındaki sayfalardır.



Enable site search?: Site içi arama desteği vermek için Y değeri verildi. Aksi durumda, N(no) değeri verilebilir.

Site içi arama

Başlığa göre arama

Enable PDF?: Pdf belgesi oluşturma desteği için Y değeri verildi. Aksi durumda, N(no) değeri verilebilir. Pdf formatı siteye erişilemediği durumda taşınabilirlik bakımından kullanışlı olacaktır.

Pdf tıklama alanı

Örnek bir pdf belgesi

Yapılandırma ayarları tanımlandıktan sonra, yapılandırma dosyası olan docfx.json dosyasının ön izlemesini gösterir. Onaylamak için Y değeri atanır, aksi halde N diyerek onaylanmaz ve tekrar yapılandırma sürecine başlarsınız.

docfx.json önizleme

Onaylandıktan sonra, aşağıdaki uyarı ile site oluşturulmuş oldu. 


Oluşturulan sitenin ayağa kaldırılması için aşağıdaki komutun çalıştırılması gerekmektedir.
docfx --serve
Bu komut ile src dosyasından csproj dosyalarında sırasıyla restore ve build işlemlerini yaparak 8080 portunda ayağa kaldırır.


Web sitesi çıktısından API'de bulunan TeamsController dosyasından dokümante edilmiş yapıyı inceleyelim.


Metotta XML summary yorum satırları mevcuttur. Web sitesine dönüştürme işlemi sonrasında çıktı, aşağıdaki gibidir.

Get metodu

Get(string) metodu

İlgili metotlarda linke tıklandığında yönlendirecek sayfaları bulunuyor. Teams olan linke tıklandığında, sonuç aşağıdaki gibidir.

Teams sınıfı

Teams.cs dosyasının kodsal görünümü aşağıdaki gibidir.

Teams.cs
Özetle;

.NET uygulamalarında kullanışlı dokümantasyon sitesini oluşturabildiğimiz docfx aracı ile görsellik sağlayıp, ekiplerin proje dokümantasyon sürecine fayda sağlar. 

Tavsiye: docfx aracından daha iyi verim alınabilmesi için XML formatındaki summary bloklarının doğru ve anlaşılır şekilde oluşturularak projenin iyi dokümante edilmesi gerekir. 

Visual Studio'daki Summary yazımı ile ilgili makaleme aşağıdaki linkten ulaşabilirsiniz.

Proje ve Docfx sitesinin bulunduğu repoya aşağıdaki Github Linkinden Ulaşabilirsiniz
Yazının faydalı olmasını umarak çalışmalarınızda kolaylıklar diliyorum :)

Kaynaklar

Yorumlar

Yorum Gönder