Sandcastle初探——官方版的NDoc

 

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 aq08good@gmail.com.”此信息从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

 

 

Chm 工具制作

需要3个工具:
Sandcastle:微软官方的,文档生成引擎
DocProject:一个文档工程插件,要基于Sandcastle安装了才能使用
HtmlHelp:微软官方的,CHM文件生成引擎

阅读更多
想对作者说点什么? 我来说一句

XML Documentation Comments Guide

2009年09月09日 495KB 下载

没有更多推荐了,返回首页

加入CSDN,享受更精准的内容推荐,与500万程序员共同成长!
关闭
关闭