使用Sandcastle生成类库说明文档示例（图文）

 

在《使用SandCastle和HTML Help 2.0集成XML代码注释到VS2005和VS2008（转）》一篇文章中讲述了如何设置SandCastle工作环境以及如何使用SandCastle生成HTML Help 2.0的帮助文档，但是HTML Help 2.0的帮助文档在没有特殊浏览器的情况下是不能查看的，所以我还是偏向于生成 HTML Help 1.x的文档。

这篇文章就用一个实例来说明如何生成一个类库项目的帮助文档以方便在类库以后的使用中方法查阅（比如我们平时自己写个通用类库，可过一段时间再使用的话可能要去看原码才可以，PS：反正我这样），主要是方便自己以后参考，如果对您也有用那就更好了。

一、使用Visual Studio 2008新建一个类型项目BookLib（为了方便说明，这里只是一个简单的类），见下图

二、在项目中添加Book类和BookType类，目录如下图：

为了方便，在每个类里添加一些方法和属性，如下：

BookType.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace BookLib
{
    /// <summary>
    /// 图书类型
    /// </summary>
    public class BookType
    {
        #region 属性
        /// <summary>
        /// 图书类型名称
        /// </summary>
        public string TypeName { get; set; }

        /// <summary>
        /// 图书类型编号
        /// </summary>
        public int TypeId { get; set; }
        #endregion

        #region 私有成员方法
        /// <summary>
        /// 查询指定的分类名称是否存在
        /// </summary>
        /// <param name="TypeName">分类名称</param>
        /// <returns>分类名称是否已存在</returns>
        private bool BookTypeExists(string TypeName)
        {
            //这里为了方便没有写具体的功能
            return false;
        }
        #endregion

        #region 公共成员方法
        /// <summary>
        /// 添加图书分类
        /// </summary>
        /// <param name="TypeName">分类名称</param>
        /// <returns>添加是否成功</returns>
        public bool AddBookType(string TypeName)
        {
            return !BookTypeExists(TypeName);
        }
        #endregion
    }
}

 

Book.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace BookLib
{
    public class Book
    {
        #region 属性
        /// <summary>
        /// 所属分类编号
        /// </summary>
        public int TypeId { get; set; }

        /// <summary>
        /// 图书名称
        /// </summary>
        public string BookName { get; set; }

        /// <summary>
        /// 图书价格
        /// </summary>
        public decimal BookPrice { get; set; }
        #endregion

        #region 成员方法
        /// <summary>
        /// 添加图书
        /// </summary>
        /// <param name="bookName">图书名称</param>
        /// <param name="bookPrice">图书价格</param>
        /// <param name="typeId">图书分类编号</param>
        /// <returns>添加是否成功</returns>
        public bool AddBook(string bookName, decimal bookPrice, int typeId)
        {
            return true;
        }

        /// <summary>
        /// 删除指定的图书
        /// </summary>
        /// <param name="bookName">要删除的图书名称</param>
        /// <returns>是否删除成功</returns>
        public bool DeleteBook(string bookName)
        {
            return true;
        }
        #endregion
    }
}

 

三、生成项目，应注意的是要将项目属性中【生成】选项卡中的XML文档文件选项设置于选中状态，如下图：

项目生成后，在bin/degug目录中生成的文件有与DLL文件同名和一个XML文件，如下图：

四、启动Sandcastle Help File Builder GUI，新建一个项目BookLibHelp（关于Sandcastle Help File Builder GUI和Sandcastle的设置见文章《使用SandCastle和HTML Help 2.0集成XML代码注释到VS2005和VS2008（转）》），如下图：

五、选择Add Documentation Source将刚刚创建的类库项目添加到项目中，见下图：

在弹出的对话框中选择BookLib类库项目，如下图：

然后在Sandcastle Help File Builder的项目浏览器中我们会看到显示了我们刚刚选择的类库项目，如下图：

六、设置Sandcastle Help File Builder的项目属性，如下图：

说明：选项很多，只说一下我们要用到的就可以了，别的如果有兴趣可以Google或Baidu
1、类库项目使用的Framework的版本
2、生成的帮助文件类型（之前说过2.0的帮助文件没有特殊的浏览器是没有办法浏览的，所以我们生成1.x的类型）
3、Sandcastle的安装路径（不知道Sandcastle是什么？请Google或Baidu一下）

七、编译项目，等待一段时间后显示编译完成在Sandcastle项目目录中的Help目录下就生成了我们类库的帮助文档，如下图：

OK，我们看一下帮助文档的内容吧，下图：

和MSDN中的一样，用起来很方便

资源下载
[1]Sandcastle October 2007 CTP下载地址：（Update：version 2.3.8000.26，Released Date：2007-10-29）
http://www.microsoft.com/downloads/details.aspx?familyid=E82EA71D-DA89-42EE-A715-696E3A4873B2&displaylang=en

[2]HTML Help Workshop下载地址：（version1.4）
http://msdn2.microsoft.com/en-us/library/ms669985.aspx

[3]Sandcastle Help File Builder下载地址：（Update：version1.6.0.1，Released Date：2007-10-31）
http://www.codeplex.com/SHFB/Release/ProjectReleases.aspx?ReleaseId=7543

 

（1）操作系统：
Windows Server 2003; Windows XP Service Pack 2; Windows Vista;

（2）必备软件：
Microsoft .NET Framework Version 2.0
HTML Help Workshop——如果需要编译生成CHM文档（需要用到其中的hhc.exe文件）

（3）可选软件：
Visual Studio 2005
MS Help Compiler from VS SDK