NAntとSandCastleでHTMLヘルプ出力(-.-)

NAnt 0.85がリリースされてたこともあって、ちょっと調べてみた。もうNDocでもないでしょってことで。

インストールが必要なもの

...

<property name="programfiles.dir" value="${environment::get-folder-path('ProgramFiles')}" />
<property name="build.dir" value="${project::get-base-directory()}/build" />

<!-- SandCastle構成 -->
<!-- ディレクトリ -->
<property name="sandcastle.dir" value="${programfiles.dir}\Sandcastle" />

<!-- 実行ファイル -->
<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" />

<!-- 変換用XSLファイル -->
<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" />

<!-- ヘルプコンパイラ -->
<property name="hhc.exe" overwrite="false" value="${programfiles.dir}\HTML Help Workshop\hhc.exe" />

...

<!-- SDKドキュメントの生成 -->
<target name="sdkdoc" depends="build" description="Builds SDK documentation">
  <property name="sandcastle.workingdir" value="${build.dir}/doc/sdk" />
  <property name="sandcastle.output.dir" value="${sandcastle.workingdir}/Output" />
  <property name="sandcastle.comments.dir" value="${sandcastle.workingdir}/comments" />

  <mkdir dir="${sandcastle.workingdir}" if="${not directory::exists(sandcastle.workingdir)}" />
  <mkdir dir="${sandcastle.output.dir}" if="${not directory::exists(sandcastle.output.dir)}" />
  <mkdir dir="${sandcastle.comments.dir}" if="${not directory::exists(sandcastle.comments.dir)}" />

  <!-- XMLコメントファイルのコピー -->
  <copy todir="${sandcastle.comments.dir}">
    <fileset basedir="${build.dir}/bin">
      <include name="${project::get-name()}.Core.xml" />
    </fileset>
  </copy>

  <!-- コンフィグレーションファイルをコピーして参照を書き換え -->
  <copy file="${sandcastle.dir}/Presentation/vs2005/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;comments\*.xml" />
    </filterchain>
  </copy>

  <!-- MRefBuilderを実行 -->
  <exec program="${sandcastle.mrefbuilder.exe}" workingdir="${sandcastle.workingdir}">
    <arg value="${build.dir}\bin\${project::get-name()}.Core.dll" />
    <arg value="/out:reflection.org.xml" />
  </exec>

  <!-- reflection.xmlの作成 -->
  <exec program="${sandcastle.xsltransform.exe}" workingdir="${sandcastle.workingdir}">
    <arg value="/xsl:&quot;${sandcastle.addoverloads.xsl}&quot;" />
    <arg value="reflection.org.xml" />
    <arg value="/xsl:&quot;${sandcastle.addguidfilenames.xsl}&quot;" />
    <arg value="/out:reflection.xml" />
  </exec>

  <!-- manifest.xmlの作成 -->
  <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>

  <!-- 出力の準備 -->
  <mkdir dir="${sandcastle.output.dir}" />
  <mkdir dir="${sandcastle.output.dir}/html" />

  <copy todir="${sandcastle.output.dir}">
    <fileset basedir="${sandcastle.dir}/Presentation/vs2005">
      <include name="icons/*" />
      <include name="scripts/*" />
      <include name="styles/*" />
    </fileset>
  </copy>

  <!-- BuildAssemblerの実行 -->
  <exec program="${sandcastle.buildassembler.exe}" workingdir="${sandcastle.workingdir}" >
    <arg value="manifest.xml" />
    <arg value="/config:Sandcastle.config" />
  </exec>

  <!-- HTMLヘルププロジェクトの作成-->
  <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>

  <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>

  <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ファイルの生成 -->
  <exec program="${hhc.exe}" commandline="test.hhp" workingdir="${sandcastle.output.dir}" failonerror="false"/>

  <copy file="${sandcastle.output.dir}/test.chm" tofile="${sandcastle.workingdir}/${project::get-name()}-SDK.chm" />

  <delete>
    <fileset basedir="${sandcastle.workingdir}">
      <include name="**/*" />
      <exclude name="${project::get-name()}-SDK.chm" />
    </fileset>
  </delete>
</target>

...

このビルドスクリプトについて簡単に説明しておこう。

SandCastleの作業用フォルダ、出力フォルダ、コンパイラで出力したXMLコメントファイルの格納フォルダをプロパティとして定義
上記フォルダの作成
コメントファイル格納フォルダにXMLコメントファイルをコピー
SandCastleのコンフィグレーションファイルをコピーしてSandCastle関連のパスと読み込むXMLコメントファイルのパスを書き換え
MRefBuilderを実行してreflection.org.xmlを出力
reflection.org.xmをreflection.xmlに変換
reflection.xmlをmanifest.xmlに変換
アイコン、スクリプト、スタイルシートのコピー
BuildAssemblerを実行
HTMLヘルププロジェクト(hhp/hhc/hhk)を作成
HTMLヘルプコンパイラでchmファイルを作成
作成したchmファイルをリネームしてコピー
不要ファイルの削除

出力されたHTMLヘルプ

＃あとは日本語のMSDNライブラリに連結させる方法を調べなきゃ。

MSBuild用のスクリプトに関する情報はここ。