Sandcastle (yazılım) - Sandcastle (software)

Sandcastle bir dokümantasyon oluşturucu itibaren Microsoft. Otomatik olarak üretir MSDN tarzı kod dokümantasyonu yansıma bilgisi .NET derlemeleri ve XML içinde bulunan dokümantasyon yorumları kaynak kodu bu meclislerin. Ayrıca üretmek için de kullanılabilir kullanıcı belgeleri itibaren Microsoft Yardım Biçimlendirme Dili (MAML) referans dokümantasyonla aynı görünüm ve hisse sahiptir.

Genel Bakış

Sandcastle bir dizi Komut satırı programlar, yapılandırma dosyaları, bileşenleri derleme ve XSLT dönüştürmek için birlikte çalışan dosyalar XML yardım sisteminde görüntülenmeye uygun yardım konularına dayalı belgeler. Sandcastle, genellikle otomatik olarak web'e hazır, XML uyumlu HTML .NET derlemelerinden üç yerleşik sunum stilinden birinde belgeler ve XML belge dosyaları tarafından oluşturulan derleyiciler. Sonuçta ortaya çıkan HTML dosyaları daha sonra aşağıdaki gibi araçlara girdi olarak kullanılır. HTML Yardım Atölyesi ilgili dağıtım için derlenmiş yardım üretmek bilgisayar programı.

Sandcastle şu anda hafif bir grafiksel kullanıcı arayüzü (GUI) bir alternatif olarak MSBuild proje toplu komut dosyası ve Windows PowerShell ayrıca sağlanan komut dosyaları. Sandcastle için ek özellikler sağlayan ve kullanımını basitleştiren çeşitli topluluk GUI araçları da mevcuttur.^[1]

Görsel stüdyo SDK'lar 2005 ve 2008 için Sandcastle'ın eski CTP sürümlerini içerir,^[2] en son sürüm şu adresten edinilebilir: GitHub.

Sandcastle araçları

Sandcastle, tümü tipik yardım oluşturma sürecinde kullanılmayan birkaç programdan oluşur. Yaygın olarak kullanılan araçlar aşağıda listelenmiştir.

• MrefBuilder kullanır Ortak Derleyici Altyapısı (CCI) yönetilen derlemelere göre düşünmek ve bir çıktı dosyası oluşturmak için.
• XslTransform, XSL dönüşümlerini bir XML dosyasına uygular. Tipik olarak, belirtilen girdi dosyası MRefBuilder tarafından oluşturulan bir dosyadır veya bu dosyadan türetilir.
• BuildAssembler, XML bildiriminde tanımlanan her konu için bir kez olmak üzere bir yapı bileşeni yığını yürütür. Bir yapı bileşeni yığını, .config uzantılı bir XML dosyasında tanımlanır. Sandcastle, bellek içi veri dizinleri oluşturma, paylaşılan içerik dahil olmak üzere bağlantıları çözme, XSL dönüşümlerini yürütme ve son çıktıyı bir dosyaya kaydetme gibi görevleri gerçekleştirmek için bileşen yığınlarında kullanılan çeşitli yapı bileşenleri sağlar.

Topluluk araçları

Sandcastle'ın mevcut durumunda tek başına kullanımı oldukça karmaşık olduğundan, insanlar görevi kendileri için otomatikleştirebilecek araçlar ve komut dosyaları geliştirdiler. Bu bölüm, bu tür araçların ve komut dosyalarının bir listesini içerir.

• Sandcastle Yardım Dosyası Oluşturucu
• DocProject (Visual Studio 2005/2008)
• Toplu dosya
• PowerShell betiği
• MSBuild komut dosyası
• Sandcastle Visual Studio Eklentisi
• Sandcastle Yardım Dosyası Oluşturucu için XML Schema Documenter

Çıktı

Sandcastle, seçilen bir sunum tarzında XML tabanlı HTML dosyaları üretir. (Ancak bu, dosyaların XHTML -uyumlu.) HTML, kullanılmakta olan belirli sunum stiline dahil olan XSL dönüştürme dosyaları tarafından tanımlanır. Bir yapı normalde bir seferde yalnızca bir sunum stili kullanır.

Sandcastle'ın ürettiği HTML dosyaları ya kavramsal (kullanıcı) dokümantasyondur ve bir dönüşümün sonucudur. Microsoft Yardım Biçimlendirme Dili (MAML) konuları veya bunlar, yansıtma verileri ve XML dokümantasyon yorumlarından otomatik olarak oluşturulan referans belgelerdir. Bu iki farklı HTML çıktısı türü aynı sunum stilini paylaşır ve karışık kullanıcı / referans belgeleri oluşturmak için birlikte derlenebilir.

Kavramsal dokümantasyon ve referans dokümantasyon oluşturma süreçleri benzerdir, temel farklardan biri kavramsal dokümantasyonun MRefBuilder programının kullanılmasını gerektirmemesidir.

Kavramsal belgeler, nasıl yapılır, gözden geçirme, sorun giderme ve diğerleri gibi bir MAML belge türü şeması kullanılarak yazılmış konuları içerir. Sandcastle, paylaşılan içeriği ve bağlantıları çözen kavramsal bir yapı bileşeni yığını (conceptual.config) sağlar ve MAML öğelerini HTML'ye dönüştürmek için XSL dosyalarını kullanır.

Yönetilenler için referans belgeler otomatik olarak oluşturulur Uygulama Programlama Arayüzleri (API'ler) yansıtma verileri ve XML dokümantasyon yorumlarından. Oluşturulacak dosyaları tanımlamak için seçilen sunum stili tarafından sağlanan bir "belge modeli" XSL dönüşümü uygulanır. Sandcastle, verilerin bellek içi dizinlerini oluşturan, paylaşılan içerik ve bağlantıları çözen ve son HTML çıktısını oluşturmak için XSL kullanan bir referans derleme bileşeni yığını (sandcastle.config) sağlar.

Derlenmiş yardım

Sandcastle derlenmiş yardım çıktısını kendisi üretmez (bununla birlikte ürettiği HTML dosyaları HTML yardım derleyicilerine girdi olarak kullanılabilir. HTML Yardım Atölyesi ve Microsoft Yardım 2 ).

Örneğin, tipik Yardım 1.x oluşturma işlemi, bir veya daha fazla derleme için bir XML yansıma dosyası oluşturmak üzere MrefBuilder.exe'yi çalıştırarak başlar. Yansıma dosyası daha sonra XslTransform.exe aracı tarafından birçok kez işlenir ve "doc modeli" ve isteğe bağlı sürüm bilgileri gibi veriler ekleyen çeşitli XSL dönüşümleri uygulanır. Ardından, XML tabanlı bir konu bildirimi oluşturulur ve yansıma verilerinden ve XML belge yorumlarından HTML konu dosyaları oluşturan BuildAssembler.exe programı tarafından kullanılır. XML tabanlı içindekiler (TOC) dosyası, BuildAssembler tarafından üretilen HTML dosyalarıyla birlikte CHMBuilder.exe tarafından oluşturulur ve kullanılır. HTML Yardım Atölyesi proje, dizin ve TOC dosyaları. Son olarak, HTML Yardımı atölyesi derlenmiş bir yardım dosyası (.chm) oluşturmak için kullanılır.

XslTransform ve BuildAssembler gibi bazı araçlar tek bir derleme sırasında birden çok kez kullanılır. Gereksinimlere bağlı olarak, Sandcastle'ın çıktısını değiştirmek için proses sırasında çeşitli aşamalarda diğer araçlar ve XSL dönüşümleri kullanılabilir.

Arka fon

Sandcastle uygulaması, Microsoft ölçeklenebilir ve performans gösteren bir dokümantasyon oluşturucu onların için API belgeler. Microsoft, Sandcastle'ı Topluluk Teknolojisi Önizlemesi olarak yayınladı (CTP ) Temmuz 2006'daki sürüm, birkaç gün önce NDoc ölü ilan edildi ^[3][4] NDoc'un yazarı Kevin Downs, posta listesi aracılığıyla gönderdiği bir e-postada, popüler aracının geliştirilmesini hem finansal hem de kalkınma katkıları olarak topluluk desteğinin olmaması, otomatikleştirilmiş bir posta bombası genel e-posta adresine ve NDoc2 posta listesi adresine saldırı ve ayrıca Sandcastle'ın "fiili standart haline geleceği ve NDoc'un yavaş yavaş durgun bir yan su haline geleceği" izlenimi.

Sandcastle günde ortalama 217 indirme yaptı ^[5] Eylül 2010'da en çok indirilen 25 projeden biri oldu CodePlex.

6 Haziran 2008'de SandCastle projesi CodePlex web sitesinden kaldırıldı^[6] CodePlex sitesindeki bir tartışma dizisinin kaynak kodun mevcut olmadığını belirttikten sonra; CodePlex'in bunu gerektirmesine ve SandCastle projesinin "açık kaynak" olarak lanse edilmesine rağmen.^[7] 2 Temmuz'da proje CodePlex'e geri döndü ve kaynak kodu yayınlandı.^[8]

Tarih

• 29 Temmuz 2006 - Temmuz 2006 CTP sürümü yayınlandı, bu sürüm esas olarak performans ve ölçeklenebilirliğe odaklandı. Hayır GUI henüz mevcuttu, uygulama çözülecek bir özellik içermiyordu GAC DLL'ler henüz.
• 28 Ağustos 2006 - Ağustos 2006 CTP sürümü yayınlandı, bu sürümde düzeltilen hatalar öncelikle uygulamanın çökmelerini düzeltmek için görünüyor. HTML uygulamanın çıktısı artık şunlarla uyumludur: Firefox. Komut satırı arayüzünde bazı değişiklikler yapıldı.
• 1 Ekim 2006 - Eylül 2006 CTP sürümü yayınlandı, hata düzeltmeleri öncelikle çıktıdaki hataları gidermeye ve bazıları için daha iyi destek eklemeye odaklanıyor gibi görünüyor XML yorum etiketleri.
• 11 Kasım 2006 - Kasım 2006 CTP sürümü yayınlandı, hata düzeltmeleriyle birlikte desteklenen diğer öğelerden bazıları nDoc etiketleri ve ayrıca dönüştürme desteği Firefox.
• 10 Aralık 2006 - Aralık 2006 CTP sürümü yayınlandı ve yapılandırma dosyaları tarafından kullanılan bir DXROOT ortam değişkeni, bir API "kopyalama" özelliği, geçiş HTML'si ve aşağıdakiler için destek içeren sunum güncellemeleri Firefox VS 2005 tarzında.
• 6 Mart 2007 - Mart 2007 CTP sürümü piyasaya sürüldü, 4 yeni eklendi ve 3 XSL dönüşümü, bir toplu derleme komut dosyası ve performans iyileştirmeleri kaldırıldı.
• 17 Mart 2007 - "Kopyalama" özelliğini ve bir yardımcı program hatasını düzelterek ve önceden yayımlanan yükleyicide eksik olan bir dosyayı içeren Mart 2007 CTP Teknik Yenileme sürümü yayınlandı.
• 19 Haziran 2007 - Haziran 2007 CTP sürümü yayınlandı ve MSBuild projesinin yeni bir versiyonu Ortak Derleyici Altyapısı (CCI) yansıtma motoru, "VS" adlı yeni bir sunum stili ORCAS ", yeni bir yapı bileşeni, yeni yürütülebilir yardımcı programlar ve diğer pek çok geliştirme.
• 27 Haziran 2007 - Haziran 2007 CTP Yenileme sürümü yayınlandı ve daha önce yayınlanan "VS ORCAS Orcas Beta 2 ve RTM belgeleri gönderildiği için karışıklığı önlemek için "Hana" sunum stili MSDN VS 2005 sunum tarzında inşa edilmeye devam edecekti.
• 1 Ekim 2007 - CHMBuilder, VersionBuilder ve DBCSFix araçlarının ilk görünümü ile Eylül 2007 CTP sürümü yayınlandı. Windows PowerShell komut dosyası oluşturun, sunum stili güncellemeleri (özellikle VS 2005 stiline) ve .NET Framework Normalde önceki yükleyicilerde bulunan yansıma dosyaları.
• 30 Ekim 2007 - Ekim 2007 CTP sürümü yayınlandı. .NET Framework önceki sürümde eksik olan dosyalar, yeni bir kavramsal dokümantasyon oluşturma süreci gerektirir. Microsoft Yardım Biçimlendirme Dili (MAML) konuları girdi olarak ve ayrıca iyileştirildi Firefox destek.
• 16 Ocak 2008 - Sandcastle'ın web'de yayınlanan ilk resmi CTP olmayan sürümü olan Sandcastle 2.4.10115 sürümü yayınlandı (RTW). Script # için bir XSL dönüşümü ve bir çıktı alma seçeneği de dahil olmak üzere örnek bir grafik kullanıcı arayüzü (GUI) sağlanmıştır. ASP.NET İnternet sitesi.

Ayrıca bakınız

• Dokümantasyon oluşturucuların karşılaştırılması

Referanslar

Dış bağlantılar

• Resmi internet sitesi