Sandcastle Help File Builder-.Netのドキュメントを生成

Sandcastle Help File Builderは、Sandcastleドキュメントジェネレーターのグラフィカルシェルです。 サンドキャッスルは、ソースコードのXMLコメントを使用した、.Net用の柔軟で機能豊富なドキュメントジェネレーターです。 これを利用して、数ステップでプロジェクトのドキュメントを作成します。

サンドキャッスルの主な機能

• XMLドキュメントにソースコードからのコメントを含める。
• リフレクションを使用して 、クラス、メソッド、プロパティ、列挙などの.Net要素に関する情報を自動的に取得します。
• 追加のHTMLページをドキュメントに統合する機能。
• いくつかの形式のドキュメント生成：Microsoftコンパイル済みHTMLヘルプ（CHM）、MS Microsoftヘルプ2（MSDN）、ウェブサイト-検索による静的および動的（ASP.NET）。

サンドキャッスルは、その作業でXMLとXSLTを使用した変換を積極的に使用しています。 すべてが非常に柔軟に実装され、簡単にカスタマイズでき、ソースコードの形で利用できます。

仕事の準備

ドキュメントを作成するには、最新の安定バージョンをインストールする必要があります。

• サンドキャッスル2008年5月リリース（バージョン2.4.10520）
• Sandcastle Help File Builder 1.7.0.0 Production

ドキュメントのテストプロジェクト

私の場合、この例を複雑にすることはなく、Hello World！アプリケーションのドキュメントを作成します。 ドキュメントには、クラスの説明、使用される名前空間、開始ページ、およびアプリケーションに関する追加情報のページが含まれます。

メインコンソールアプリケーションクラス：

using System;

using System.Text;



namespace Atv.Research.HelloWorld

{

/// <summary>

///

/// </summary>

public class Program

{

/// <summary>

///

/// </summary>

/// <param name="args"> </param>

public static void Main( string [] args)

{

Console .Out.WriteLine( "Hello World!" );

}

}

}



* This source code was highlighted with Source Code Highlighter .

プロジェクトのプロパティで、コメントを使用してXMLファイルの生成を設定する必要があります。 これを行うには、プロジェクトの[プロパティ] / [ビルド]タブ/ [出力]セクションのコンテキストメニューで[XMLドキュメントファイル]チェックボックスをオンにします。 プロジェクトをコンパイルした後、 Atv.Research.HelloWorld.exeアプリケーションとAtv.Research.HelloWorld.XMLコメントファイルを取得します 。



ドキュメントにいくつかの静的ページを追加してみましょう。 コードからの技術情報では不十分なことがよくあります。 図や図を含む、より一般的な説明が必要です。 または、たとえば、Webサービスの構成ファイルまたはWSDLのテキスト全体を挿入します。 例として、2つの静的HTMLページを挿入します。 それらの1つがドキュメントの出発点になります。



Index.htm

<! DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" >

<!-- @DefaultTopic -->

< html xmlns ="http://www.w3.org/1999/xhtml" >

< head >

< title > About </ title >

</ head >

< body >

< div style ="height:140px;" >   </ div >

< div style ="text-align:center" >

< h1 > < br /> Hello World! </ h1 >



< div >< a href ="Details.htm" > </ a ></ div >

</ div >



</ body >

</ html >



* This source code was highlighted with Source Code Highlighter .

Details.htm

<! DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" >

< html xmlns ="http://www.w3.org/1999/xhtml" >

< head >

< title > Details </ title >

</ head >

< body >

< h2 > </ h2 >

< p > "Hello World" Sandcastle. </ p >

< h2 > </ h2 >

: < see cref ="Atv.Research.HelloWorld.MyTestClass" />



< h2 > "The Code Block Component" </ h2 >

< pre lang ="cs" numberLines ="true" outlining ="true"

title ="Example of Syntax Highlighting" >

// Test method

public void TestMethod(string s, int x)

{

// Debug code

x = x + 1;

s = x.ToString();

Console.WriteLine("The string = " + s);

}

</ pre >



</ body >

</ html >



* This source code was highlighted with Source Code Highlighter .

ここでは、次のことに注意する必要があります。

• @DefaultTopic-コメントは、このページが開始ページになることを示すために使用されます。
• <see>タグは、静的ページから、特定のクラス、メソッド、または名前空間を含むソースコードに関する自動生成ドキュメントのページにリンクするのに役立ちます。
• <pre>タグ-静的ページのコードサンプルで構文を強調表示します。

これらおよびその他の組み込み機能については、Sandcastle Help File Builderのドキュメントで説明されています。

プログラムの開始

実際、すでに入力データがあります。 これは、アプリケーション、XMLコメントファイル、およびアプリケーションを説明する2つの静的ページです。 それでは、Sandcastle Help File Builder GUIを起動します。



SandcastleヘルプファイルビルダーGUIメインウィンドウ

1. アセンブリとXMLファイルをドキュメントとともに追加します。この場合、 Atv.Research.HelloWorld.exeとAtv.Research.HelloWorld.XMLです。
2. プロジェクトの一般的な説明を追加します。
3. 適切に構造化され説明された名前空間の説明を追加します-それらはプロジェクト内をより良くナビゲートするのに役立ちます。 この情報はすべて、受け取ったドキュメントに反映されます。
4. プロジェクト設定を実施します。 必須のものと、すぐに注意を払う必要があるものだけをリストします。
   
   

   パラメータ	価値	説明
   追加の概念的なコンテンツ
   追加コンテンツ	開いた追加ウィンドウで、[ファイル]ボタンを使用してIndex.htmおよびDetails.htmページを追加します。	追加の静的HTMLページ。
   構築する
   コンポーネント構成	開いたウィンドウで[コードブロックコンポーネント]を選択します。	これを使用して、静的ページの構文を強調表示します。
   FrameworkVersion	2.0.50727	ここでアプリケーションで使用されている.Netのバージョンを示します。
   HelpFileFormat	Help1xAnd2xAndWebsite	1つまたは複数の出力形式を選択します：HtmlHelp1x / HtmlHelp2x / WebSite。
   ヘルプファイル
   ヘルプタイトル	テストコンソールアプリケーション	私たちの見出し
   Htmlhelpname	HelloWorldApplication	ヘルプ出力ファイル名
   PresentationStyle	vs2005	ここにあなたの好みがあります。私は「hana」や「Prototype」ではなく「vs2005」に精通しています。
   Rootootspacecontainer	本当	クラスの説明を個別のヘルプノードに分けます。
   RootNamespaceTitle	名前空間	そして彼に私たちの名前を付けます
   パス
   HtmlHelp1xCompilerPath	C：\ Program Files \ HTML Help Workshop \	HTML Path ヘルプワークショップとドキュメント
   HtmlHelp2xCompilerPath	C：\ Program Files \ Common Files \ Microsoft Shared \ Help 2.0 Compiler \	Visual Studio SDK（2003/2005/2008）とともにインストールされるMicrosoft Help SDKへのパス（ Visual Studio 2008 SDK 1.1など）
   出力パス	。\ HelpResult \	完成したドキュメントがコピーされるパス
   サンドキャッスルパス	C：\ Program Files \ Sandcastle \	サンドキャッスルの道、好みに合わせて調整
   ワーキングパス	。\ SandcastleWorkingFolder \	作業の中間結果が追加される作業フォルダーへのパス

   さらに、各ページの上部と下部に表示されるテキスト、著作権の行、フィードバック用のリンクをカスタマイズできます。 プライベートで安全なメソッドとプロパティを文書化するかどうかを示します。 コードにXMLコメントがない場合に警告を有効にします。 設定の詳細な説明は、常に添付のドキュメントに記載されています。 ただし、Sandcastle Help File BuilderはSandcastleのグラフィカルなアドオンであり、必要に応じて直接使用できることを忘れないでください。
   
   
5. 再利用のためにプロジェクトを保存します。
6. ドキュメントを作成しています。

作業結果

1. Microsoftコンパイル済みHTMLヘルプ（CHM）

CHMとしてヘルプ





CHMヘルプ-静的ページ

2. MS Microsoftヘルプ2

MSDN形式の統合ヘルプ

3.静的ウェブサイト

プレーンHTMLページのヘルプ

4.動的Webサイト（ASP.NET）

検索を使用して動的なサイトの形でヘルプ

追加情報

上記で使用したすべてのコード、ヘルプファイルビルダープロジェクト、およびその作業の結果は、 narod.yandex.ruまたはdrop.io （391KB）のSandcastleTestProject.zipアーカイブにあります。



さらなる研究のためのリンク：

• CodePlexのSandcastle
• CodePlexのSandcastleヘルプファイルビルダー
• Habr上のC＃のXMLドキュメント

Sandcastleの基本的な機能のみを示しました。 それがあなたにとって興味深いものであり、まだ使用していないのであれば、今すぐ試してみてください。 ご清聴ありがとうございました。