Sandcastleでドキュメントを作成する

ライブラリ等のドキュメントを生成します。インストール方法は、Sandcastleをインストールするを参考にしてください。(2007/06/20時点)

使用するSandcastleは、Sandcastle - June 2007 Community Technology Preview (CTP)です。

ドキュメントの作成

Sandcastleをインストールしたフォルダに、Examples\Sandcastleフォルダが作成されています。このフォルダには、C#のプロジェクトと ドキュメントを生成するバッチファイルが用意されています。(build_Sandcastle.bat)

実際にドキュメントを生成する際は、このバッチファイルを修正して使用すると良いのではないでしょうか?

build_Sandcastle.batの中及び使い方

Sandcastleの各ツールのパスやHTML Help Workshopのパスを通します。

set PATH=c:\WINDOWS\Microsoft.NET\Framework\v2.0.50727;%DXROOT%\ProductionTools;
         C:\Program Files\HTML Help Workshop;
         C:\Program Files\Microsoft Help 2.0 SDK;%PATH%

次にドキュメントを作成する対象となるソースをコンパイルしています。

csc /t:library /doc:comments.xml test.cs

このコンパイル部分をMSBuildに置き換えて次のようにします。

msbuild ..\..\..\%2.sln /p:Configuration=DEBUG;DocumentationFile=%2.xml /t:Clean,Build

コンパイルが終了すると、Sandcastleで提供されるツール(MRefBuilder)でメンバー変数やメソッドが 独自のXMLで出力されます。(reflection.org)

MRefBuilder test.dll /out:reflection.org

この部分も次のように修正します。

MRefBuilder %2.dll /out:reflection.org

Sandcastleでは、VS2005、ORCAS、Prototypeの3種類のフォーマットでの出力が用意されています。 ここで、変換が行われreflection.xml、manifest.xmlが作成されます。

if {%1} == {vs2005} (
  XslTransform /xsl:"%DXROOT%\ProductionTransforms\ApplyVSDocModel.xsl" reflection.org _
             /xsl:"%DXROOT%\ProductionTransforms\AddFriendlyFilenames.xsl" _
             /out:reflection.xml /arg:IncludeAllMembersTopic=true _
             /arg:IncludeInheritedOverloadTopics=true
) else if {%1} == {vsorcas} (
  XslTransform /xsl:"%DXROOT%\ProductionTransforms\ApplyVSDocModel.xsl" reflection.org _
             /xsl:"%DXROOT%\ProductionTransforms\AddFriendlyFilenames.xsl" _
             /out:reflection.xml /arg:IncludeAllMembersTopic=false _
             /arg:IncludeInheritedOverloadTopics=true
) else (
  XslTransform /xsl:"%DXROOT%\ProductionTransforms\ApplyPrototypeDocModel.xsl" reflection.org _
               /xsl:"%DXROOT%\ProductionTransforms\AddGuidFilenames.xsl" _
               /out:reflection.xml 
)


XslTransform /xsl:"%DXROOT%\ProductionTransforms\ReflectionToManifest.xsl"  reflection.xml _
             /out:manifest.xml

フォーマットに合わせた、作業ディレクトリ及び画像ファイルのコピーが行われます。

call "%DXROOT%\Presentation\%1\copyOutput.bat"

BuildAssemblerでOutput\htmlフォルダへドキュメントのHTMLファイルが生成されます。

BuildAssembler /config:"%DXROOT%\Presentation\%1\configuration\sandcastle.config" manifest.xml

HTML HelpWorkshop用のプロジェクトファイルへ変換します。

XslTransform /xsl:"%DXROOT%\ProductionTransforms\ReflectionToChmProject.xsl" reflection.xml /out:Output\test.hhp

TOC(目次)を作成します。

if {%1} == {prototype} (
XslTransform /xsl:"%DXROOT%\ProductionTransforms\createPrototypetoc.xsl" reflection.xml /out:toc.xml 
) else (
XslTransform /xsl:"%DXROOT%\ProductionTransforms\createvstoc.xsl" reflection.xml /out:toc.xml 
)

HTML Helpを作成します。

XslTransform /xsl:"%DXROOT%\ProductionTransforms\TocToChmContents.xsl" toc.xml /out:Output\test.hhc

XslTransform /xsl:"%DXROOT%\ProductionTransforms\ReflectionToChmIndex.xsl" reflection.xml /out:Output\test.hhk

hhc output\test.hhp

build_Sandcastle.bat改

Sandcastleのサンプルについてくるバッチを少しだけ修正しました。(build_Sandcastle)

使い方は、ソリューションのDebugフォルダにバッチファイルをコピーし、次のように実行します。

build_Sandcastle.bat vs2005 ターゲット名