利用SandCastle制作类似MSDN的帮助

     因为需要生成公司公用类库的帮助文档,这几天来,我一直在研究SandCastle,现在把我使用的心得说一下,权当记录,留作以后查阅方便.

      软件的安装就比较简单了，从网上下载最新版本的SandCastle，双击安装就OK了，安装路径默认，因为时间的关系，我并没有试如果更改安装路径会不会引起软件的异常，推荐还是用默认的路径吧。SandCastle是一个命令行工具，本身并不提供操作界面，在命令行下的工作方法我就不做说明了，这位兄弟的博客中写的比较清晰:http://www.cnblogs.com/netatomy/archive/2008/01/24/1050769.html.

     不管怎样，用命令行的方式编译实在是有点不方便，以下推荐一款界面操作工具：Sandcastle Help File Builder（太长了，以下简单SH)，这个工具比较好用，当然也是英文版的（头疼），该工具从网上也是可以免费下载的，安装过程也比较简单，不再多说。

在使用SH中有一些细节需要注意：
（1）使用SH之前需要确认已经安装Sandcastle和HTML Help Workshop
（2）HTML Help Workshop的安装路径最好是程序默认安装路径，笔者就曾因为自定义了安装了路径导致

      以上需注意的两个细节也是从其他同行的博客中摘抄的，我并没有试。

 

安装完成以后，打开，界面应该很熟悉吧，很像VS，呵呵，以下开始用这个工具工作;

首先新建一个项目，File－>New Project,选择一个路径保存。保存成功以后就可以在右侧的Project Explore中看到以下两项:

 

上面的Documentation Sources中加入要生成帮助文档的文件,包括DLL和XML文件,如果不加XML文件,生成的帮助中没有注释.另外在添加DLL文件的时候,如果文件夹下有同名的XML文件,系统自动加载.下面的Reference中包含引用文件,这个不用多说了,也就是说我上图中的SandTest.dll中如果引用了其他的DLL,在References中必须加入进来,如果不加,在编译时会提示错误,而且错误提示也不明确,只是说有错误,这个地方要注意.接下来设置项目属性,在左侧的Project Properties中有很多项,我没有一个一个的试,只是大体理解其用途,一会在文章的后面列出来.

在生成帮助的过程中,遇到的最棘手的问题就是示例代码的嵌入,SH的帮助文件看了很久,也没有多少头绪,加上<Code>标识以后生成的帮助文件中也没有对应的示例,这个问题困扰了很久,求助于MSDN论坛,也没有得到解决方法.在一个偶然的机会,看到一个同行的博客里面也有相应介绍SandCastle的文章(地址忘记了,感谢那位兄弟),里面有一段代码文件,我下载了以后,自己建立项目,然后生成对应的DLL文件和XML文件,把生成的XML文件和我从前的XML文件比较,发现他的里面多了一个<example>标识,问题就出在这里,只有加了这个标识,编译的时候才会建立示例代码.以下是我修改后的XML文件的一部分:

   <example>
   <code>
      string a;
      string b;
   </code>
   </example>

这种是将示例代码写到XML文件中,还有一种通过读外部文件的方式:

<example>
   <code source="../Examples/Add.cs"/>
 </example>

以上两种方式都已经测试通过.

以上成功嵌入示例代码都是用SH做的,在命令行下用SandCastle编译,我试了一下,没有相应的示例代码(不清楚原因),而且里面也是英文,所以还是推荐用SH做.

 

下面是属性的大体说明,我的英文不好,理解的可能有问题:

BuildLogFile: 编译时产生的日志文件放置的目录,不填也可以

CleanIntermediates:是否删除在编译时生成的中间文件(例如HTML页面啥的),如果想要在编译后再修改HTML页面,此项需设置成false

ComponentConfigurations:里面是几个编译的组件,我没有具体去试,其中有一个Code Block Component组件,看上面的说明是产生示例代码的,但是我没有加入这个,生成的帮助也是有示例代码的.

CppCommentsFixup:这个属性不明白啥意思

FrameworkVersion:.NetFrameWork的版本,默认是2.0,因为我们的程序是在VS2008环境下开发的,所以我选择的是3.5,这个根据情况自己设置

HelpFileFormat:帮助文件格式,推荐默认吧,没具体看

KeepLogFile:是否保存日志文件,如果设置为true,日志会一直保存,如果设置成false,日志文件会被删除

PlugInConfigurations,UserDefinedProperties这两个属性我一打开设置系统就崩了,所以没试,不太明白有什么作用

Comments:下面有两个属性NamespaceSummaries,ProjectSummary这两个一个是命名空间的描述,一个是工程描述,不多说

ContentPlacement:没仔细研究,推荐默认

CopyrightHref:字面理解是版权声明的链结地址,我填的是一个网址,生成帮助文件后会生成一个超链接.

CopyrightText:版权声明的文字说明

FeedbackEMailAddress:反馈邮箱地址

FeedbackEMailLinkText:反馈邮箱上的文字说明

FooterText,HeaderText:类似于WORD中的页眉和页脚.

HelpTitle:帮助文件标题(在生成的帮助文件中每个页面中都会出现这个)

HtmlHelpName:生成的帮助文件的名称

IndentHtml:不太理解,再研究吧

Language:语文,也就是显示在帮助文件页面中的说明文字所用的语言,如果要生成中文的,必须选择中文(中华人民共和国)

NamingMethod:不太明白,推荐默认

Preliminary:这个选项如果设置成true,会在生成的帮助文件的每个页面(可能只是部分页面,不确认)的头部分生成一名话:[此文档为预发布版本，在未来版本中有可能改变。]

PresentationStyle:显示样式,推荐vs2005,其他两项我没有试,不知道生成的是什么样式

ProjectLinkType,RootNamespaceContainer,RootNamespaceTitle,SdkLinkTarget,SdkLinkType:这几个不明白啥意思,默认吧

ShowFeedbackControl:是否显示发送有关此主题的意见这个超链接

SyntaxFilters:语法过滤,生成的帮助文件中显示哪种语言,如果选择多个的话生成的帮助文件会像MSDN一样,在页面的最上方会多一个语言选择的下拉列表

HTML Help 1,HTML Help 2:这两个里面的属性都不太明白

Paths:这个里面的几个属性是设置工作路径的,不再多说,需要注意的是SandcastlePath这个属性,要设置成SandCastle的安装路径.

AutoDocumentConstructors: 是否自动生成一个默认的构造函数(不确认)

Show Missing Tags中其他的几项就是在缺少注释的情况下是否给出警告信息,比如我写了一个方法,没有给这个方法加注释,那么在生成的帮助中就会用红色字体给出提示,比较的难看.这几项我都设置成了false

Visibility: 这个里面的几个属性我都没有试,推荐默认吧.

 

 

以上的内容是个人的一些总结,如果大家使用过程中还有其他的问题可以发贴讨论一下.