使用 Sandcastle、NAnt 和 CruiseControl.NET 生成 MSDN 风格的文档
3.81/5 (12投票s)
使用 CruiseControl.NET 运行 Sandcastle 的 NAnt 任务
引言
本文介绍了使用 Sandcastle 通过 NAnt（一种脚本语言）生成 MSDN 风格文档的步骤。这些脚本是为从 CruiseControl.NET 项目启动而开发的，但您也可以轻松地直接从 NAnt 启动它们。
背景
Sandcastle 是微软新的 MSDN 风格文档生成器。Sandcastle 组件通过反射收集有关您的程序集的信息，并将其与源代码中的 XML 注释结合。输出是一组 HTML 页面，您可以选择将其编译为 CHM 或 HxS 格式。本文提出的 NAnt 脚本是 CruiseControl.NET 项目的一部分，并密切遵循了在此官方 Sandcastle 博客文章中详细阐述的 12 个生成 CHM 的步骤，并在上图中有图形表示。
准备工作
提出的 NAnt 脚本集将在以下假设下工作
- 您要为其生成文档的应用程序已成功编译。您的程序集存储在一个目录中，该目录的路径存储在名为
${bin.intern.dir}的 NAnt 属性中。 - 提取的 XML 文档文件位于由
${documentation.dir}属性引用的目录中——它们是通过使用您喜欢的编译器的/doc命令行参数生成的。 - 所有依赖的第三方程序集（例如 Infragistics、Composite UI Application Block、Liquid XML Library、Wilson OR Mapper）都位于一个目录中，该目录的路径存储在
${bin.extern.dir}属性中。
代码
属性部分
为了保持构建脚本的核心部分的可读性和可维护性，让我们先为所有固定的目录、可执行文件和 XSL 转换路径创建一些属性。
<!-- Directories -->
<property name="sandcastle.dir"
value="F:\Program Files\Sandcastle" />
<property name="sandcastle.workingdir"
value="${projects.dir}\${CCNetProject}\SandcastleWorkingDir" />
<property name="sandcastle.output.dir"
value="${sandcastle.workingdir}\Output" />
<!-- Executables -->
<property name="sandcastle.mrefbuilder.exe"
value="${sandcastle.dir}\productiontools\mrefbuilder.exe" />
<property name="sandcastle.buildassembler.exe"
value="${sandcastle.dir}\productiontools\buildassembler.exe" />
<property name="sandcastle.xsltransform.exe"
value="${sandcastle.dir}\productiontools\xsltransform.exe" />
<!-- Transformations -->
<property name="sandcastle.addoverloads.xsl"
value="${sandcastle.dir}\ProductionTransforms\AddOverloads.xsl" />
<property name="sandcastle.addguidfilenames.xsl"
value="${sandcastle.dir}\ProductionTransforms\AddGuidFilenames.xsl" />
<property name="sandcastle.reflectiontomanifest.xsl"
value="${sandcastle.dir}\ProductionTransforms\ReflectionToManifest.xsl" />
<property name="sandcastle.reflectiontochmproject.xsl"
value="${sandcastle.dir}\ProductionTransforms\ReflectionToChmProject.xsl" />
<property name="sandcastle.reflectiontochmcontents.xsl"
value="${sandcastle.dir}\ProductionTransforms\ReflectionToChmContents.xsl" />
<property name="sandcastle.reflectiontochmindex.xsl"
value="${sandcastle.dir}\ProductionTransforms\ReflectionToChmIndex.xsl" />
<!-- Help Compiler -->
<property name="hhc.exe" overwrite="false"
value="F:\Program Files\HTML Help Workshop\hhc.exe" />
创建空工作目录
NAnt 项目中的第一个任务是创建空工作目录。
<!-- Create or Cleanup Working Directory -->
<mkdir dir="${sandcastle.workingdir}"
if="${not directory::exists(sandcastle.workingdir)}" />
<delete>
<fileset basedir="${sandcastle.workingdir}">
<include name="**\*" />
</fileset>
</delete>
准备 BuildAssembler 的输入
创建实际 HTML 文档的 Sandcastle 组件是所谓的 BuildAssembler。它需要三个输入文件：
- reflection.xml
- sandcastle.config
- manifest.xml
以下步骤将创建这些文件：
创建配置文件
此 NAnt 任务会将原始的 sandcastle.config 文件复制到工作目录。原始文件中的相对路径将替换为固定路径，我们将内置的对 comments.xml 文件的引用替换为对包含我们自己的程序集 XML 文档的文件夹的引用。
<!-- Copy configuration file, and hard code references -->
<copy file="${sandcastle.dir}/Presentation/Configuration/Sandcastle.config"
tofile="${sandcastle.workingdir}/Sandcastle.config">
<filterchain>
<replacestring from=""..\..\" to=""${sandcastle.dir}\" />
<replacestring from=""..\" to=""${sandcastle.dir}\Examples\" />
<replacestring from=""comments.xml" to=""${documentation.dir}\*.xml" />
</filterchain>
</copy>
创建初始反射文件
MRefBuilder 是 Sandcastle 的核心控制台应用程序之一。它使用反射创建一个 XML 文件，该文件描述了一组程序集的内部结构。其完整的命令行包含：
- 程序集列表（支持通配符）。
- /out：XML 输出文件。
- /dep：逗号分隔的依赖程序集列表（允许通配符）。
- /internal+|- 指定是否生成内部 API 和外部 API。
<!-- Run MRefBuilder (introspection on assemblies) to create basic Reflection XML -->
<exec program="${sandcastle.mrefbuilder.exe}" workingdir="${sandcastle.workingdir}">
<arg value="${bin.intern.dir}/*.dll" />
<arg value="${bin.intern.dir}/*.exe" />
<arg value="/out:reflection.org1.xml" />
<arg value="/dep:${bin.extern.dir}\*.dll" />
</exec>
MRefBuilder 生成的文件 -reflection.org- 包含两种类型的 XML 元素：
<assembly>：程序集元数据（版本、描述、公司等）。<api>：命名空间、类型、成员、构造函数等。
创建最终的 Reflection.xml 文件
这些任务创建最终的 Reflection.xml 文件，其中包含所有必需的信息，但没有任何表示。使用 Sandcastle 的 XSLTransform 工具，我们在 reflection.org 文件上应用两个 XSL 转换。
- 原始的列表方法和构造函数是扁平的，首先我们必须按重载对这些主题进行分组。
- 然后，我们为每个主题添加 HTML 文件的名称。
可以将两个转换分步应用，但我将其分开以便于验证结果。
<!-- Create final Reflection XML -->
<!-- Regroup overloads -->
<exec program="${sandcastle.xsltransform.exe}" workingdir="${sandcastle.workingdir}">
<arg value="reflection.org1.xml" />
<arg value="/xsl:"${sandcastle.addoverloads.xsl}"" />
<arg value="/out:reflection.org2.xml" />
</exec>
<!-- Create filenames for html documents -->
<exec program="${sandcastle.xsltransform.exe}" workingdir="${sandcastle.workingdir}">
<arg value="reflection.org2.xml" />
<arg value="/xsl:"${sandcastle.addguidfilenames.xsl}"" />
<arg value="/out:reflection.xml" />
</exec>
如果您想将此目录暴露给您的应用程序的最终用户，那么您可能不会使用 GUID 作为文件名。我建议创建一个自己的转换作为 addguidfilenames.xsl 的替代方案。
创建清单
所谓的 Manifest 又是另一个 XML 文件。它是 Topic 条目的列表，每个 <api> -element 在 reflection.xml 中对应一个条目。
<!-- Create Manifest (list of Topics) -->
<exec program="${sandcastle.xsltransform.exe}" workingdir="${sandcastle.workingdir}">
<arg value="/xsl:"${sandcastle.reflectiontomanifest.xsl}"" />
<arg value="reflection.xml" />
<arg value="/out:manifest.xml" />
</exec>
生成 HTML 文档
准备输出环境
输出目录有四个子文件夹。BuildAssembler 工具将在 html 子文件夹中生成其文档，art、scripts 和 styles 文件夹是从安装中复制的。它们包含必要的脚本、样式表和图像，以使文档具有 MSDN 的外观和感觉。
<!-- Create Output Environment -->
<mkdir dir="${sandcastle.output.dir}" />
<mkdir dir="${sandcastle.output.dir}/html" />
<copy todir="${sandcastle.output.dir}">
<fileset basedir="${sandcastle.dir}/Presentation">
<include name="art/*" />
<include name="scripts/*" />
<include name="styles/*" />
</fileset>
</copy>
生成 HTML 文档
BuildAssembler 是一个通用的控制台应用程序。它将 XML 文档（reflection.xml）通过一个组件管道（如转换器、文件创建器、流程控制器等）。管道是通过 sandcastle.config 构建的，并为每个主题（即 manifest.xml 中的每个条目）执行。BuildAssembler 的命令行包含对 manifest.xml 文件和 sandcastle.config 的引用。对 reflection.xml 和包含 XML 源文档的文件的链接存储在 config 文件中。
<!-- Run BuildAssembler (create html topic files) -->
<exec program="${sandcastle.buildassembler.exe}" workingdir="${sandcastle.workingdir}" >
<arg value="manifest.xml" />
<arg value="/config:Sandcastle.config" />
</exec>
此过程的输出是一个目录，其中包含每个主题的链接 HTML 文件。arts、scripts 和 styles 文件夹中的文件应用了 MSDN 的外观和感觉。文档功能齐全，其余过程是可选的。
生成 CHM 文件
接下来的任务通过 HTML Help Workshop 将当前的 Output 目录转换为单个 CHM 文件。
创建 HTML Help Compiler 的输入
HTML Help compiler 需要三个输入文件：
- 一个包含内容的.*hhp文件)，
- 一个包含目录（.*hhc）的文件。
- 一个索引文件（.*hhk）。
这些输入文件都是 XML 文件，可以通过在 reflection.xml 上应用 XSL 转换来生成。
<!-- Create html Help project -->
<exec program="${sandcastle.xsltransform.exe}" workingdir="${sandcastle.workingdir}">
<arg value="/xsl:"${sandcastle.reflectiontochmproject.xsl}"" />
<arg value="reflection.xml" />
<arg value="/out:"${sandcastle.output.dir}\test.hhp"" />
</exec>
<!-- Create html Help project Table Of Contents -->
<exec program="${sandcastle.xsltransform.exe}" workingdir="${sandcastle.workingdir}" >
<arg value="/xsl:"${sandcastle.reflectiontochmcontents.xsl}"" />
<arg value="reflection.xml" />
<arg value="/arg:html=Output\html" />
<arg value="/out:"${sandcastle.output.dir}\test.hhc"" />
</exec>
<!-- Create html Help project Index -->
<exec program="${sandcastle.xsltransform.exe}" workingdir="${sandcastle.workingdir}" >
<arg value="/xsl:"${sandcastle.reflectiontochmindex.xsl}"" />
<arg value="reflection.xml" />
<arg value="/out:"${sandcastle.output.dir}\test.hhk"" />
</exec>
编译帮助项目
最后，我们通过 Microsoft HTML Help Compiler (v1.4) 将项目编译为 CHM 文件。我不得不将 failonerror 设置为 false 以忽略非零的返回值。
<!-- Generate CHM file -->
<exec program="${hhc.exe}"
commandline="test.hhp"
workingdir="${sandcastle.output.dir}"
failonerror="false"/>
历史
- 2006 年 9 月 4 日：本文的初始版本
关于 Diederik Krols
Diederik Krols 是一位 .NET 架构师和培训师。作为一名认证的 Scrum Master，他拥抱所有能够尽可能保持开发速度和质量，并将开销降至最低的工具。他在 Real Developer Network 上发布了许多关于 CruiseControl.NET 和开源 N*Stack（NAnt、NUnit、NCover 等）其他组件的文章。他的 个人博客 包含有关反模式的文章。