Visual Studio Otomatik Dokümantasyon Oluşturma.

Bir programcı için güvenilir belgeler her zaman bir zorunluluktur. Belgelerin varlığı bir uygulamanın tüm yönlerini takip etmeye yardımcı olur ve bir yazılım ürününün kalitesini artırır.SandCastle popüler belge üreticilerinden biridir.Buna bir alternatif ararken DocFx’in yeni olduğunu ve daha popüler hale geldiğini buldum Yani denemek istiyorum.

DocFX nedir?

DocFx , Microsoft tarafından geliştirilmiş bir dokümantasyon aracıdır. Açık kaynak kodludur ve .NET Core projeleri için büyük desteğe sahiptir.

Ana Özellikler

• Kaynak
  Koddan web sitesi DocFX, doğrudan .NET kaynak kodundan API belgeleri oluşturur. Markdown sözdizimini kaynak koddaki Triple-Slash-Comments öğesinde kullanabilirsiniz. Markdown dosyalarını kullanarak API belgelerine ek konular eklemenize bile izin verir. Elbette saf Markdown dosyaları da desteklenmektedir. Tek bir komutta hem kavramsal konuları hem de API konularını içeren statik web sitenizi oluşturabilirsiniz.
• Her Yerde Çalıştır
  DocFX, Linux, macOS ve Windows üzerinde çalışabilir. Oluşturulan web sitesi tamamen statiktir ve Github Sayfalarına, Azure Web Sitelerine veya ek yapılandırması olmayan herhangi bir web ana bilgisayarına dağıtılabilir.
• Kolay Özelleştirme
  DocFX, şablonları ve temaları kolayca özelleştirmek için esnek bir yol sağlar. Ve .NET core ile geliştirilir ve .NET core docs tarafından kullanılır.

KURULUM

Visual studio kullanarak bir .NET core projesi oluşturun.

XML yorumlarını etkinleştirin. Benim durumumda test dışında altı projem var. Bu yüzden her proje için etkinleştirmek zorundasınız. XML Yorumlarını etkinleştirmek için Bir projeye sağ tıklayın ve özelliklere gidin.

Şahsen belgelerin olması için en iyi yerin projenin kökünde “Belgeler” adı verilen klasörün altında olduğunu hissediyorum. Çözümün bulunduğu dosya gezgini’ne gidin.

DocFX’i kurmak için Chocolatey’e ihtiyacımız var. Chocolatey’i kurmak için CMD’yi yönetici modunda açın ve aşağıdaki komutu çalıştırın.

@”%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe” -NoProfile -InputFormat None -ExecutionPolicy Bypass -Command “iex ((New-Object System.Net.WebClient).DownloadString(‘https://chocolatey.org/install.ps1'))" && SET “PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin”

kurulum talimatlarını burada bulabilirsiniz .

Sonra DocFX.Noteate’i proje kök klasörüne kurmalı ve cmd’yi yönetici olarak açmalı ve aşağıdaki komutu çalıştırmalıyız.

cinst docfx -y

Belgeler klasörü altında belge projesi oluşturmak için aşağıdaki komutu çalıştırın.

docfx init -q -o Belgeler

Sonra Api referanslarını göstermeliyiz.Bunu yapmak için docfx.json dosyasını açın ve src klasörünü işaret etmek için “cwd”: “..” ekleyin.

Bu, src klasörü altındaki tüm projeler için belge oluşturur.

Bunu test etmek için sınıflarıma ve arayüzlerime bazı XML yorumları ekledim.

Belgeleri oluşturmak için Belgeler klasörünün içinde gezinin ve cmd’yi yönetici olarak açın.

docfx --serve

Bu, dokümantasyonu oluşturur ve http://localhost:8080 URL’sinde siteye hizmet eder . Bu url’ye gidersek statik Api dokümantasyon sitesini görebiliriz.

Önemli : .NET Core ile çalışıyorsak, VSINSTALLDIR ve VisualStudioVersion ortam değişkenlerini ayarlamamız gerekebilir, aksi takdirde DocFx projelerimizi oluşturamaz. VS 2017 için bu açık Geliştirici Komut İstemi’ni ayarlamak için (cortana’da kolayca bulun) ve aşağıdaki komutu çalıştırın.

SET VSINSTALLDIR=C:\Program Files (x86)\Microsoft Visual Studio17\BuildTools
SET VisualStudioVersion=15.0

DocFx özel temaları ve eklentileri destekler.İsterseniz bunları kullanabilirsiniz.Ayrıca bu statik bir site olduğu için makaleler oluşturabilirsiniz.