Sandcastle|Sandcastle 学习教程 (1) 基础入门
概要 目前可找到SandCastle学习资源十分有限。而据我所知能够生成帮助文档的工具目前只有SandCastle(NDoc早就已经停止更新了,参见“相关文档”中的第二篇。)
有关XML注释,我曾经写过两篇文章,里面也简单介绍了如何使用SandCastle:
- 使用.NET中的XML注释(一) -- XML注释标签讲解
- 使用.NET中的XML注释(二) -- 创建帮助文档入门篇
本系列教程希望能够深入的研究SandCastle,比如SandCastle的各个组件,高级的使用技巧,如何与持续构造(FinalBuilder)继承等。
本篇文档翻译自SandCastle的两篇官方文档。目前官方文档只能找到下面翻译的内容。
一.SandCastle介绍 Sandcastle是托管类库的文档编译器,用来生成微软风格的API接口说明和程序结构说明的帮助文档。通过反射关联的.NET Framework 程序集,使用源代码中的 XML文档注释(在C#中的“///”或者VB中的“’”)生成API接口说明文档。通过反射dll文件创建程序结构说明,其他的比如提醒和参数等信息都是通过源代码中的XML注释导出的。
生成的文档如下图所示:
文章图片
二. SandCastle特性 SandCastle是由微软提供的用于生成.Net帮助文档的工具,可以生成API接口说明和程序结构说明。
- 支持.NET Framework 2.0
- 使用VersionBuilder工具支持不同版本的项目
- 使用CHMBuilder 工具用来生成HTML 1.x版本的chm文件。
- 符合 Visual Studio 2008 的帮助主题
- 使用Windows的PowerShell脚本生成文档接口说明
- 支持5星MSDN风格的投票反馈
三. 系统要求 操作系统
- Windows Server 2003;
- Windows Vista;
- Windows XP Service Pack 2
- .NET Framework 2.0, 可以在.NET Framework网站下载。
- HTML Help Workshop,支持HTML 1.x 文件,可以通过 HTML Help 下载站点下载,或者通过Visual Studio SDK 安装。
- MS Help 2.0 Compiler,支持HTML 2.0 文件,是VS2005或更新的版本安装时的一部分,可以支持生成HTML 2.0(.Hxs)文件。
- Visual Studio 2005,可以与帮助文档集成。
- 确定机器上已经安装了HTML Help Workshop,创建Help 2.0(HxS)文件还需要Help 2.0 Compiler。Visual Studio 2008 SDK已经包括了这两部分。
- 卸载早期的SandCastle版本(不是随着Visual Studio 2008 SDK安装的)。
- 从CodePlex下载 SandCastle Installer, 并运行安装程序。
如果想要安装Visual Studio 2008 SDK,请在安装SandCastle之前安装。这是因为Visual Studio 2008 SDK 安装时更新了PATH和DXROOT两个系统注册的变量。如果在SandCastle安装后这两个变量被更新,将导致SandCastle无法工作。如果已经安装了SandCastle,有下面两个方法:
- 安装Visual Studio 2008 SDK后,卸载SandCastle,重新安装SandCastle。
- 重新设置PATH和DXROOT两个环境变量
在AMD64机器上设置SandCastle
- 在开始菜单上,在“我的电脑”上单击鼠标右键,选择“属性”。
- 在左侧的区域中,单击“高级系统设置”。
- 在“高级”标签中单击“环境变量”按钮。
- 在“环境变量”中找到“PATH”,单击“编辑”。
- 将下面的变量添加到属性值中:
%ProgramFiles(x86)%\HTML Help Workshop; %ProgramFiles(x86)%\Common Files\Microsoft Shared\Help 2.0 Compiler
推荐阅读
- Python基础|Python基础 - 练习1
- Java|Java基础——数组
- Java基础-高级特性-枚举实现状态机
- 营养基础学20180331(课间随笔)??
- iOS面试题--基础
- HTML基础--基本概念--跟着李南江学编程
- typeScript入门基础介绍
- c++基础概念笔记
- 集体释放
- 自我修养--基础知识