Sandcastle初探——官方版的NDoc

Posted 2022-11-13 Snowdust

Sandcastle初探——官方版的NDoc

Sandcastle（CodeName）是微软出的用于编译发布组件（Assembly）信息的一个工具，基本上等同于NDoc（后者目前已经停止开发，最新版本仍然不支持.Net 2.0）。这个工具通过反射和Xslt技术，可以从dll文件及其xml注释（编译时加/doc参数得到），得到一个完整的帮助文档，格式可以是html或CHM甚至是任何自定义的格式。当前Sandcastle最新版本是June CTP。使用方式仍然是命令行，而官方网站上给出的使用说明只能支持单一的Dll，也就是Project，对于Solution仍然没有任何说明。其Blog上介绍说以后会有GUI和VS.Net 2005 Add-In等使用方式。现在让我们来先睹为快。

Sandcastle June CTP的下载地址http://www.microsoft.com/downloads/details.aspx?FamilyID=e82ea71d-da89-42ee-a715-696e3a4873b2&DisplayLang=en，如果你需要编译生成CHM文档，还需要HTML Help Workshop，下载地址http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp

以上两个文件的安装很简单，一直点击下一步就可以成功安装。安装时强烈建议使用默认的路径。

编译文档的方法有两种，一种是使用我写的Bat文件（前提是安装使用的是默认路径），下载地址/Files/yuandong/sandcastlebuild.rar：使用方法如下：

1． 下载并安装Sandcastle和HTML Help Workshop，使用默认路径。

2． 点这里下载编译文件，解压缩。包含三个文件：build.bat，build.config，build.hhp。

3． 将以上三个文件拷贝到Project的bin的Debug目录下。（假设要编译的组件名成为Assembly，确定目录下至少包含Assembly.dll和Assembly.xml，后者为XML注释。如何产生XML注释参见http://msdn2.microsoft.com/zh-CN/library/b2s063f7.aspx ）

4． 开一个CMD，导航到Debug目录。

5． 键入“build 组件名”上例中即为“Build Assembly”。

6． 生成的文件在Debug的Output目录下。

以下为我生成的CHM的截图：

 

下的“组件名＋Html”目录下为Html格式的文件，名称使用的是GUID，一般来说大小最小的为首页，复制一个，改名为Index.htm就可以发布了。以下为Html的截图：

 

 

请注意上图最低部的版权信息：“(c) It.ouc.edu.cn. All rights reserved. Send comments about this topic to [e-mail].”此信息从C:/Program Files/Sandcastle/Presentation/Content/shared_content.xml里面设置（默认是微软）。

 

从截图中可以看到，Sandcastle对中文的支持很好，而且生成的默认格式是我们再熟悉不过的MSDN风格。

注意，以上方法只适合没有依赖的组件，对于有依赖的组件，需要修改Bat文件，详细方法在Bat文件中有详细的注释。

第二种编译的方法是官方发布的方法，详情参看https://blogs.msdn.com/sandcastle/archive/2006/07/29/682398.aspx，E文很简单，我就不翻译了。这种方法比较麻烦，有问题的可以留言讨论。

从以上介绍可以看出，Standcastle的编译生成已经很成熟了，而且从分析来看，其可定执行相当强大。只是使用方法还很简陋，离实际使用还有距离，毕竟还是CTP版本。不过相信微软的东西，最终易用性应该是让人满意的。更多内容可以参考：

https://blogs.msdn.com/sandcastle/default.aspx

http://forums.microsoft.com/MSDN/ShowForum.aspx?ForumID=66&SiteID=1

或留言讨论。

Output