创建专业级别的类库使用文档——Sandcastle十一月份CTP发布

序

一个人的相貌对他的事业、家庭、生活方面的成功有多重要？或者说人的能力和相貌那个重要？虽然所有人、包括整个社会都在回避这个问题。文明社会在发展的过程中也逐渐对例如种族、性别、性取向歧视等作了法律上的约束。但一个仍旧不争的事实依然是：大部分时间里，人的想法都是出于本能，也就是所谓的“激素决定”的，“以貌取人”仍旧是这个社会的主流。

软件的界面和软件的功能哪个重要？相信那些学院出身的、理论先行的朋友自然会说功能。而如果你曾经在小型公司里工作过，或是和客户（特别是国内的政府客户）打过直接交道，或是在业内已经做了一定的时间，或者学过一些心理学知识，那么将不得不至少在心里默默认可界面的地位。

人首先是动物，然后才是人。

对于类库形式的软件来说，文档就是它给用户的界面。即使你不认同我上面的说法，懒于做这些“表面上”的工作，但现在免费的Sandcastle已经摆在你面前了，何不尝试一下轻松做出专业级别类库文档的快乐呢？园子里那么优秀的NBear，是否可以考虑一下呢？

 

使用Sandcastle创建专业的类库使用文档

最新的Sandcastle十一月CTP就是这样一个微软开发的免费的类库文档自动生成工具，可以在这里下载。Sandcastle需要操作系统为Windows 2003或XP SP2，需要安装.NET Framework 2.0以及HTML Help Workshop（这里下载）。

下载页面中还对Sandcastle有一个简单的介绍，如下（非常简单，就不翻译了）：

Sandcastle produces accurate, MSDN style, comprehensive documentation by reflecting over the source assemblies and optionally integrating XML Documentation Comments. Sandcastle has the following key features:

1. Works with or without authored comments
2. Supports Generics and .NET Framework 2.0
3. Sandcastle has 2 main components (MrefBuilder and Build Assembler)
4. MrefBuilder generates reflection xml file for Build Assembler
5. Build Assembler includes syntax generation, transformation..etc
6. Sandcastle is used internally to build .Net Framework documentation

下载安装完成之后，即可参考这篇文章以命令行的形式生成类似MSDN一般的CHM文档了。这篇文章同样非常简单，只有几个步骤而已，这里不赘。

 

使用SandcastleGUI让使用文档更加专业

SandcastleGUI是一个GUI程序，可以在http://www.inchl.nl/SandcastleGUI/下载。该GUI封装了命令行形式提供的Sandcastle，并对其有了非常强大的扩充：

1. 自动在文档中插入MSDN文章链接
2. 可以选择程序集中的某个命名空间生成文档，而不是默认的整个程序集
3. 多种输出方式：网站、CHM帮助文件或输出二者
4. 自定义帮助文档头部（公司LOGO以及产品名称等）
5. 自定义帮助文章页脚（版权信息等）
6. 在文档中插入自定义的图像
7. 文档的代码实例中将C#语法高亮显示

SandcastleGUI可以生成如下样式的文档（极为震撼）：

SandcastleGUI的界面如下，同样非常简洁：

 

 

相关资源

 

1. Sandcastle Help Forum
2. Sandcastle Wiki
3. Sandcastle Blogs
4. Create CHM or HxS build using Sandcastle
5. SandcastleGUI
6. HTML Help Workshop

 

写作感想

1. 这一段时间写得比较多，学会忙里偷闲写个Blog也是个能力啊，嘿嘿
2. 这一周的任务不少，要修改4章书稿，还要给《程序员》写篇文章，努力吧……