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 ターゲット名