简介
本文介绍的步骤来生成MSDN样式的文档Sandcastle的,使用NAnt,一种脚本语言。脚本开发开始从CruiseControl.NET项目,但您可以轻松地直接从南特开始他们以及。背景
Sandcastle是微软的MSDN风格的文档的新发电机。 Sandcastle的组件通过反射收集有关您的程序集的信息,并结合从源代码的XML注释。输出是一个HTML页面,你可以选择编译CHM或HXS格式的设置。 NAnt的脚本,我在这篇文章中提出的一个CruiseControl.NET项目的一部分,并密切跟踪的12个步骤生成} {A0阐述了一个CHM,在上面的图片,并以图形代表。制备
NAnt的脚本提出将工作在以下假设:你要生成文档的应用程序的编译成功。你自己的程序集存储在其中的路径是在一个名为$ {bin.intern.dir}一个NAnt的属性中存储目录所提取的XML文档文件位于目录$ {documentation.dir}属性 - 使用/ DOC您最喜爱的编译器的命令行参数生成所有的依赖第三方组件(如Infragistics,复合UI应用程序块,液体XML库,威尔逊或映射)是位于一个单独的目录的路径存储在$ {bin.extern.dir}属性。守则物业组
为了保持buildscripts的可读性和可维护性的核心,让我们先创建所有的固定目录的路径来,可执行文件,和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" />
在南特项目的第一项任务是创建一个空的工作目录:{C}准备BuildAssembler输入
创建实际的HTML文档Sandcastle的组成部分,是所谓的BuildAssembler。它有三个输入文件:reflection.xmlsandcastle.config的manifest.xml
下面的步骤创建这些文件:创建配置文件
这南特任务的原始sandcastle.config文件复制到工作目录。在原始文件中的相对路径所取代固定的路径,我们更换内置的参考与我们自己的程序集的XML文档的文件夹中包含的参考comments.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文件,它描述了一个程序集的内部结构。其完整的命令行中包含:列表中的程序集(支持通配符)输入/输出:XML输出文件/ DEP:逗号分隔的依赖程序集清单(允许使用通配符)/内部| - 到指定是否生成内部和外部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元素:LT; assemblygt;:程序集元数据(版本,说明,公司,...)LT; apigt;:命名空间,类型,成员,构造,...创建最终Reflection.xml文件
这些任务创建的最后Reflection.xml文件,其中包含所有必要的信息,但没有任何文稿在。使用Sandcastle的XslTransform的工具,我们采用两个XSL转换上的reflection.org文件:原来的列表的方法和构造是平的,首先我们必须重载小组,由这些主题然后,我们添加的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替代。创建清单
所谓的清单又是一个XML文件。这是一个主题的条目的列表,每个LT之一; apigt;从reflection.xml元素。
生成的HTML文档准备输出环境<!-- 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>
输出目录有四个子文件夹。 BuildAssembler工具将生成其文档中的HTML的子文件夹,美术,剧本,并从安装文件夹中复制的风格。他们包含必要的脚本,样式表和图像文档,它的MSDN看起来和感觉。
生成HTML文档<!-- 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>
BuildAssembler是一个通用的控制台应用程序。它通过管道元件(如transformators,文件的创作者,流量控制器,...).发送一个XML文档(reflection.xml)这条管道是通过sandcastle.config构建,并为每个主题的执行(即在manifest.xml的每个条目)。 BuildAssemblers命令行组成的manifest.xml文件和sandcastle.config。 reflection.xml和包含的XML源代码文件的文件存储在配置文件中。<!-- 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文件的目录。艺术,脚本和样式文件夹中的文件,申请一个MSDN的外观和感觉。该文档的全部功能,过程的其余部分是可选的。生成CHM文件
接下来的任务转换电流输出目录到一个CHM文件,通过HTML Help Workshop的。创建HTML帮助编译器的输入
HTML帮助编译器预计3个输入文件:一个文件的内容(*. HHP),与目录文件(*. HHC)一个索引文件(*. HHK)
输入文件都可以申请reflection.xml XSL转换生成的XML文件:
编译帮助项目<!-- 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>
最后,我们的项目编译CHM文件通过Microsoft HTML帮助编译器(V1.4)。我只好把虚假的failonerror忽略返回非零值。
历史2006年9月4日:本文的初始版本关于Diederik Krols<!-- Generate CHM file -->
<exec program="${hhc.exe}"
commandline="test.hhp"
workingdir="${sandcastle.output.dir}"
failonerror="false"/>
Diederik Krols。NET师和培训师。作为认证Scrum Master的,他包含了所有工具,保持尽可能高的发展速度和质量,并尽可能低的开销。他已发布CruiseControl.NET和其他组件的开源的许多文章,N *堆栈(南特,NUnit的,NCover,... ...)包含反模式的文章。