VS文檔生成神器(Sandcastle)

Sandcastle是一個(gè)管理類庫(kù)的文檔編譯器，是用于編譯發(fā)布組件（Assembly）信息的一個(gè)工具，這個(gè)工具通過反射和Xslt技術(shù)，可以從dll文件及其xml注釋（命令行編譯時(shí)加/doc參數(shù)或vs2005設(shè)置項(xiàng)目屬性得到）得到一個(gè)完整的幫助文檔，格式可以是Html或CHM甚至是任何自定義的格式。

Sandcastle中組件：

MrefBuilder、BuildAssembler和XslTransform。這些工具使用編譯匯編代碼時(shí)生成的輸出結(jié)果，包括DLL文件以及XML注釋文件。

MrefBuilder反射一個(gè)項(xiàng)目的匯編代碼并生成一個(gè)輸出文件。MrefBuilder是一個(gè)隨Sandcastle安裝的命令行工具。它生成的輸出文件通過XslTransform命令行工具轉(zhuǎn)換成一個(gè)叫做reflection.xml的文件。reflection.xml文件包含所有文檔數(shù)據(jù)，但不提供顯示細(xì)節(jié)。

MrefBuilder完成工作后，立即由BuildAssembler接手處理。BuildAssembler可由命令行工具BuildAssembler啟動(dòng)。它利用由MrefBuilder生成的數(shù)據(jù)(reflection.xml)和任何代碼注釋（保存在獨(dú)立的XML文件中），生成按邏輯分組的HTML文件。HTMLHelpCompiler再利用這些HTML文件生成最終結(jié)果。

該工具并未限制你一次處理一個(gè)匯編。如果你需要處理幾個(gè)匯編代碼，你必須深入了解Sandcastle配置文件。它是一個(gè)包含建立幫助文件主題所需步驟的XML文件。

andcastle生成的輸出結(jié)果特點(diǎn)：

1、類似于MSDN布局的界面。

2、自動(dòng)生成索引項(xiàng)、內(nèi)容項(xiàng)目表、主題塊和頁面布局，提高一致性和熟悉程度。

3、自動(dòng)生成語法宣稱部分。

4、自動(dòng)生成繼承表。

5、代碼彩色化。

6、提供多種風(fēng)格和語言選擇，終端用戶可從中選擇自己最喜歡的形式。

7、輸出結(jié)果以HTML和CSS形式顯示，微軟承諾將來提供更多選擇。

Sandcastle示例：

Sandcastle是微軟提供的一個(gè)根據(jù)XML注釋和DLL文件生成幫助文件的工具，目前是在CodePlex上的一個(gè)開源項(xiàng)目。

第一步，為你寫的代碼添加XML注釋

我們創(chuàng)建一個(gè)簡(jiǎn)單的ClassLibrary1項(xiàng)目最為示范：

usingSystem;usingSystem.Collections.Generic;usingSystem.Text;namespaceClassLibrary1{///<summary///AsampleclasstoshowsomethingusingSandcastle///</summarypublicclassSampleClass{privatestring_propertyValue;///<summary///Getsorsetsthepropertyvalue.///</summary///<valueThepropertyvalue.</valuepublicstringProperty{get{return_propertyValue;}set{_propertyValue=value;}}///<summary///Determineswhetherthepropertyisnull.///</summary///<returns///??<ctrue</cifpropertyisnull;otherwise,<cfalse</c.///</returnspublicboolIsPropertyNull(){boolresult=false;if(this.Property==null){result=true;}returnresult;}///<summary///Determineswhetherthepropertyisnull.///</summary///<returns///??<ctrue</cifpropertyisempty;otherwise,<cfalse</c.///</returns///<example///Thisexampleshowshowyoumightusethismethod://////<code///SampleClasssample=newSampleClass();//////if(sample.IsPropertyEmpty())///{///????Console.WriteLine("Thepropertyisempty");///}///else///{///????Console.WriteLine("Thepropertycontainsvalue"+sample.Property);///}///</code///</examplepublicboolIsPropertyEmpty(){boolresult=this.IsPropertyNull();if(!result){result=(Property.Trim().Length==0);}returnresult;}}}

代碼很簡(jiǎn)單，注意其中的XML注釋。

打開項(xiàng)目的屬性，在“Build”選項(xiàng)中，確保“XMLdocumentationfile:”被選中了。

第二步，編譯這個(gè)項(xiàng)目，你會(huì)看到生成的DLL文件和XMl文件：

第三步，打開SandcastleHelpFileBuilder

打開SandcastleHelpFileBuilder并新建一個(gè)項(xiàng)目：

為SandcastleHelpFileBuilder項(xiàng)目添加編譯生成的DLL文件，右鍵點(diǎn)擊項(xiàng)目右邊的“DocumentationSources",選擇“AddDocumentationSource...”

選擇剛剛生成的DLL文件。

第四步，修改設(shè)置

在項(xiàng)目的屬性窗口，你可以根據(jù)需要修改一些設(shè)置。

第五步，生成文檔

點(diǎn)擊Buildthehelpfile來生成文檔。

這是最終生成的文檔：

Tags:文檔編譯器.