使用 Sandcastle 生成代码帮助文档

Posted 2020-08-12 菜鸟程序员

使用 Sandcastle可以生成MSDN风格的帮助文档，生成的帮助文档既可以是chm文档，也可以是MS Help 2.x帮助文档。

 

1 下载并安装Sandcastle

Sandcastle下载地址为：http://sandcastle.codeplex.com/

 

2 下载并安装html Help Workshop

HTML Help Workshop可以用来生成chm文件，有的系统可能已经安装了HTML Help Workshop，HTML Help Workshop的默认安装路径为C:\Program Files (x86)\HTML Help Workshop,安装前可先到此目录下进行确认，若已经安装无须再安装。若需要重新安装最好使用默认安装路径。

HTML Help Workshop下载地址为：http://dl.pconline.com.cn/html_2/1/87/id=1917&pn=0.html

 

3 准备程序集和文档注释文件

Sandcastle生成帮助文档是基于代码编译后生成的程序集和文档注释文件来工作的。要想在代码编译过程中能生成文档注释文件，需要在VS中进行如下配置。

 

设置工程输出时包含XML文档文件，这样就会生成文档注释文件。

例：新建工程SandcastleExp，仅包含代码文件Student.cs，编译代码，在bin\Debug目录下的生成的SandcastleExp.dll和SandcastleExp.XML文件就是Sandcastle工具所需要的输入内容。

 

4 使用命令行方式操作Sandcastle生成帮助文档

将步骤3生成的SandcastleExp.dll和SandcastleExp.XML文件拷贝至C:\test文件夹（也可以是其他自建的任意文件夹）,再将C:\Program Files (x86)\Sandcastle\Examples\Sandcastle（Sandcastle安装路径）下的批处理文件build_Sandcastle.bat拷贝至此文件夹。

使用cmd打开命令行窗口，进入该目录，输入命令：build_sandcastle.bat vs2005 SandcastleExp chm，回车。

成功执行后，会生成如下所示的chm文件。

 注意：第一次安装Sandcastle后需要重启电脑，否则运行build_sandcastle.bat会出错。因为安装Sandcastle 后会创建一个系统环境变量 DXROOT，不重启电脑，该环境变量不会起作用。

 

3 使用图形用户界面的方式生成帮助文档

Sandcastle还提供了图形用户界面供用户操作。可执行文件为C:\Program Files (x86)\Sandcastle\Examples\Generic\SandcastleGui.exe。打开程序，并进行相关设置，界面如下。

 

点击“Build”后，在C:\Program Files (x86)\Sandcastle\Examples\test\vs2005\chm下生成chm帮助文件。

注意：必须使用管理员账户来运行程序。

在Win8环境下，需要修改C:\Program Files (x86)\Sandcastle\Examples\Generic\Generic.targets文件，具体修改内容如下：

    <When Condition="Exists(‘$(ProgramFiles) (x86)‘)">

      <PropertyGroup>

        <ToolsPath>$(ProgramFiles(x86)) </ToolsPath>

      </PropertyGroup>

</When>

将其中的“$(ProgramFiles(x86)) ”修改为“$(ProgramFiles) (x86) ”（注意：中间还有空格）否则程序无法生成chm文件。

 关于代码注释规范，请自行网补。

转载自：http://blog.csdn.net/yl2isoft/article/details/18454115