Geekly Articles each Day

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

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

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

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

仕事の準備


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

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


私の場合、この例を複雑にすることはなく、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 .


ここでは、次のことに注意する必要があります。これらおよびその他の組み込み機能については、Sandcastle Help File Builderのドキュメントで説明されています。

プログラムの開始


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

SandcastleヘルプファイルビルダーGUIメインウィンドウ
«Sandcastle Help File Builder GUI»
  1. アセンブリとXMLファイルをドキュメントとともに追加します。この場合、 Atv.Research.HelloWorld.exeとAtv.Research.HelloWorld.XMLです。
  2. プロジェクトの一般的な説明を追加します。
  3. 適切に構造化され説明された名前空間の説明を追加します-それらはプロジェクト内をより良くナビゲートするのに役立ちます。 この情報はすべて、受け取ったドキュメントに反映されます。
  4. プロジェクト設定を実施します。 必須のものと、すぐに注意を払う必要があるものだけをリストします。
    パラメータ価値説明
    追加の概念的なコンテンツ
    追加コンテンツ開いた追加ウィンドウで、[ファイル]ボタンを使用してIndex.htmおよびDetails.htmページを追加します。追加の静的HTMLページ。
    構築する
    コンポーネント構成開いたウィンドウで[コードブロックコンポーネント]を選択します。これを使用して、静的ページの構文を強調表示します。
    FrameworkVersion2.0.50727ここでアプリケーションで使用されている.Netのバージョンを示します。
    HelpFileFormatHelp1xAnd2xAndWebsite1つまたは複数の出力形式を選択します：HtmlHelp1x / HtmlHelp2x / WebSite。
    ヘルプファイル
    ヘルプタイトルテストコンソールアプリケーション私たちの見出し
    HtmlhelpnameHelloWorldApplicationヘルプ出力ファイル名
    PresentationStylevs2005ここにあなたの好みがあります。私は「hana」や「Prototype」ではなく「vs2005」に精通しています。
    Rootootspacecontainer本当クラスの説明を個別のヘルプノードに分けます。
    RootNamespaceTitle名前空間そして彼に私たちの名前を付けます
    パス
    HtmlHelp1xCompilerPathC：\ Program Files \ HTML Help Workshop \HTML Path ヘルプワークショップとドキュメント
    HtmlHelp2xCompilerPathC：\ 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ヘルプ-静的ページ
CHM -

2. MS Microsoftヘルプ2

MSDN形式の統合ヘルプ
MSDN

3.静的ウェブサイト

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

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

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

追加情報


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

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

Source: https://habr.com/ru/post/J68227/

More articles:


All Articles