Sandcastle 入门

引言

本文将引导您完成从安装 Sandcastle 到生成第一个 Sandcastle 帮助文档的步骤。 假设您已经知道如何在 Visual Studio 中生成 XML 注释以及 Sandcastle 是什么。

背景

文档总是让一些程序员喜欢抱怨和呜咽的东西（好吧，至少我是这样）。当有人问我是怎么做的时候，我说“我不知道，谁在乎呢？它做了它应该做的事情！”。好吧，文档坚持我们对这个问题有一个答案。Visual Studio 使文档记录变得容易且有用！按 (/) 三次允许您创建 XML 注释以输入函数数据。这不仅对 intellisense 有用，而且对文档也很有用。

Sandcastle 是一个程序，它将“可能”痛苦的文档过程变成点击几次鼠标按钮（除了添加 XML 注释之外）。 目前还没有关于如何启动和运行 Sandcastle 的正式文档。 因此，为了让您免去像我一样在 Internet 上搜索的麻烦，我创建了本教程。

安装

要开始使用，您需要以下内容

• Visual Studio 2005 SDK
• Sandcastle - Sandcastle 后端
• Sandcastle Help File Builder - Sandcastle 的众多前端之一（IMO 这是最好的）
• HTML Help Workshop - 查看帮助文档

构建您的帮助文档

Visual Studio 设置

在构建文档之前，您必须确保构建 XML 文档文件。 该文件本身没有用处； 但是，Sandcastle 需要它才能构建帮助文档。

在 Visual Studio 2005 中，转到项目 -> 属性并选择生成选项卡，并确保在输出下方的 XML 文档复选框已选中

重要的是要注意 XML 文件应采用“mylibraryname”.xml 格式！ 在此示例中，库名称为“Sample”。 现在您可以构建项目，并且可以将其导出为 Sandcastle 帮助文档。

Sandcastle 帮助文件生成器

• 从开始 -> 程序文件打开 Sandcastle 帮助文件生成器 (SHFB)。
• 在 Sandcastle 帮助文件生成器中，选择项目 -> 从 Visual Studio 项目新建项目...，然后打开您在上一步（Visual Studio 设置）中构建 XML 文档的*.sln。
• 在 SHFB 中的项目属性窗口内的HelpFileFormat属性中定义帮助文件格式。（选择 Help1xAndWebsite，因为 IMO 网站看起来最好）。
• 定义OutputPath属性。（项目属性窗口）
• 选择文档 -> 构建项目

就是这样，您完成了。 您可以通过已安装的 HTML 帮助工作室程序加载 *.chm 文件，或者如果您已将其导出为网站，则可以打开 index.html 文件。 这两个文件都位于您在 SHFB 的OutputPath属性中指定的目录中。

我建议您也阅读

• Sandcastle 帮助文件生成器- 深入了解 SHFB 的精彩文章

历史

• 2008 年 11 月 4 日：首次发布