返回首页


简介
本文介绍的步骤来生成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="&quot;..\..\" to="&quot;${sandcastle.dir}\" /> 

      <replacestring from="&quot;..\" to="&quot;${sandcastle.dir}\Examples\" />

      <replacestring from="&quot;comments.xml" to="&quot;${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:&quot;${sandcastle.addoverloads.xsl}&quot;" />

   <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:&quot;${sandcastle.addguidfilenames.xsl}&quot;" />

   <arg value="/out:reflection.xml" />

</exec>

,如果您想揭露这个目录您的应用程序的最终用户,那么你可能会不使用文件名的GUID。我建议创建你自己的转型addguidfilenames.xsl替代。创建清单
所谓的清单又是一个XML文件。这是一个主题的条目的列表,每个LT之一; apigt;从reflection.xml元素。
<!-- Create Manifest (list of Topics) -->

<exec program="${sandcastle.xsltransform.exe}" workingdir="${sandcastle.workingdir}">

   <arg value="/xsl:&quot;${sandcastle.reflectiontomanifest.xsl}&quot;" />

   <arg value="reflection.xml" />

   <arg value="/out:manifest.xml" />

</exec>
生成的HTML文档准备输出环境
输出目录有四个子文件夹。 BuildAssembler工具将生成其文档中的HTML的子文件夹,美术,剧本,并从安装文件夹中复制的风格。他们包含必要的脚本,样式表和图像文档,它的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是一个通用的控制台应用程序。它通过管道元件(如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:&quot;${sandcastle.reflectiontochmproject.xsl}&quot;" />

   <arg value="reflection.xml" />

   <arg value="/out:&quot;${sandcastle.output.dir}\test.hhp&quot;" />

</exec>

<!-- Create html Help project Table Of Contents -->

<exec program="${sandcastle.xsltransform.exe}" workingdir="${sandcastle.workingdir}" >

   <arg value="/xsl:&quot;${sandcastle.reflectiontochmcontents.xsl}&quot;" />

   <arg value="reflection.xml" />

   <arg value="/arg:html=Output\html" />

   <arg value="/out:&quot;${sandcastle.output.dir}\test.hhc&quot;" />

</exec>

<!-- Create html Help project Index -->

<exec program="${sandcastle.xsltransform.exe}" workingdir="${sandcastle.workingdir}" >

   <arg value="/xsl:&quot;${sandcastle.reflectiontochmindex.xsl}&quot;" />

   <arg value="reflection.xml" />

   <arg value="/out:&quot;${sandcastle.output.dir}\test.hhk&quot;" />

</exec>
编译帮助项目
最后,我们的项目编译CHM文件通过Microsoft HTML帮助编译器(V1.4)。我只好把虚假的failonerror忽略返回非零值。
<!-- 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的,他包含了所有工具,保持尽可能高的发展速度和质量,并尽可能低的开销。他已发布CruiseControl.NET和其他组件的开源的许多文章,N *堆栈(南特,NUnit的,NCover,... ...)包含反模式的文章。

回答

评论会员:StickyC 时间:2011/12/07
感谢优秀的新手必看 - 我们已经实现了它在这里和它的伟大工程

在此过程完成后时,我们已经有了HTML页面以及每个主题目录,有一个简单的方法也产生HTML网站作为输出的一部分,如果你选择的网站,你会得到类似Sandcastle的帮助文件生成器图形用户界面的输出?我还没有找到这里被称为命令行实用程序的详细文档。
评论会员:Zoggs 时间:2011/12/07
大文章

我很新的巡航控制,很高兴今天上午,在我的CC托盘的绿色图标。

你内运行CC的脚本,使每签更新?
评论会员:取决于 时间:2011/12/07
我想是这样
。技术上的文件应更新为每个建设。
评论会员:SkySigal 时间:2011/12/07
真正干净的形象,创建有... ...什么软件包?
评论会员:DiederikKrols 时间:2011/12/07
相信它或不是:它是用PowerPoint {S1}完成。我不得不承认,花了几个小时。
评论会员:SkySigal 时间:2011/12/07
您确保有足够的耐心
看起来绝对大

我一直在寻找*永世周围*一个很好的工具,一个不喜欢你制作的图片...
如果有谁知道,一个好的包,可以接近上面的图像(但在较短的时间
我们线!
评论会员:snider123 时间:2011/12/07
Microsoft Visio中的
评论会员:下蹲 时间:2011/12/07
Macromedia Fireworks中行之有效太