Sandcastle初探——官方版的NDoc

 

Sandcastle初探——官方版的NDoc

SandcastleCodeName)是微软出的用于编译发布组件(Assembly)信息的一个工具,基本上等同于NDoc(后者目前已经停止开发,最新版本仍然不支持.Net 2.0)。这个工具通过反射和Xslt技术,可以从dll文件及其xml注释(编译时加/doc参数得到),得到一个完整的帮助文档,格式可以是HtmlCHM甚至是任何自定义的格式。当前Sandcastle最新版本是June CTP。使用方式仍然是命令行,而官方网站上给出的使用说明只能支持单一的Dll,也就是Project,对于Solution仍然没有任何说明。其Blog上介绍说以后会有GUIVS.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. 下载并安装SandcastleHTML Help Workshop,使用默认路径。

2. 这里下载编译文件,解压缩。包含三个文件:build.batbuild.configbuild.hhp

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

4. 开一个CMD,导航到Debug目录。

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

6. 生成的文件在DebugOutput目录下。

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

Sandcastle初探——官方版的NDoc_第1张图片
Output下的“组件名+Html”目录下为Html格式的文件,名称使用的是GUID,一般来说大小最小的为首页,复制一个,改名为Index.htm就可以发布了。以下为Html的截图:

 

Sandcastle初探——官方版的NDoc_第2张图片

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

 

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

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

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

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

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

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

或留言讨论。

你可能感兴趣的:(cast)