VS文档生成神器(Sandcastle)

Sandcastle是一个管理类库的文档编译器，是用于编译发布组件（Assembly）信息的一个工具，这个工具通过反射和Xslt技术，可以从dll文件及其xml注释（命令行编译时加/doc参数或vs2005设置项目属性得到）得到一个完整的帮助文档，格式可以是Html或CHM甚至是任何自定义的格式。

Sandcastle中组件：

MrefBuilder、BuildAssembler和XslTransform。这些工具使用编译汇编代码时生成的输出结果，包括DLL文件以及XML注释文件。

MrefBuilder反射一个项目的汇编代码并生成一个输出文件。MrefBuilder是一个随Sandcastle安装的命令行工具。它生成的输出文件通过XslTransform命令行工具转换成一个叫做reflection.xml的文件。reflection.xml文件包含所有文档数据，但不提供显示细节。

MrefBuilder完成工作后，立即由BuildAssembler接手处理。BuildAssembler可由命令行工具BuildAssembler启动。它利用由MrefBuilder生成的数据(reflection.xml)和任何代码注释（保存在独立的XML文件中），生成按逻辑分组的HTML文件。HTMLHelpCompiler再利用这些HTML文件生成最终结果。

该工具并未限制你一次处理一个汇编。如果你需要处理几个汇编代码，你必须深入了解Sandcastle配置文件。它是一个包含建立帮助文件主题所需步骤的XML文件。

andcastle生成的输出结果特点：

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

2、自动生成索引项、内容项目表、主题块和页面布局，提高一致性和熟悉程度。

3、自动生成语法宣称部分。

4、自动生成继承表。

5、代码彩色化。

6、提供多种风格和语言选择，终端用户可从中选择自己最喜欢的形式。

7、输出结果以HTML和CSS形式显示，微软承诺将来提供更多选择。

Sandcastle示例：

Sandcastle是微软提供的一个根据XML注释和DLL文件生成帮助文件的工具，目前是在CodePlex上的一个开源项目。

第一步，为你写的代码添加XML注释

我们创建一个简单的ClassLibrary1项目最为示范：

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;}}}

代码很简单，注意其中的XML注释。

打开项目的属性，在“Build”选项中，确保“XMLdocumentationfile:”被选中了。

第二步，编译这个项目，你会看到生成的DLL文件和XMl文件：

第三步，打开SandcastleHelpFileBuilder

打开SandcastleHelpFileBuilder并新建一个项目：

为SandcastleHelpFileBuilder项目添加编译生成的DLL文件，右键点击项目右边的“DocumentationSources",选择“AddDocumentationSource...”

选择刚刚生成的DLL文件。

第四步，修改设置

在项目的属性窗口，你可以根据需要修改一些设置。

第五步，生成文档

点击Buildthehelpfile来生成文档。

这是最终生成的文档：

Tags:文档编译器.