« 親コンテナを無効にしても子コントロールを灰色表示にしない方法 | トップページ | Sandcastle を使用したドキュメント作成(2) »

2010年11月 1日 (月)

Sandcastle を使用したドキュメント作成(1)

Sandcastle の現在の最新版は http://sandcastle.codeplex.com/ にある様です。ちなみに現時点での最新バーションは、June 2010 Release(Version 2.6.1062.1)です。また、その前のバージョン May 2008 Release(Version 2.4.10520) もダウンロード可能です。
また、Sandcastle のフロントエンドツール、Sandcastle Help File Builder は、http://shfb.codeplex.com/ にあり、現在の最新版は v1.9.1.0 ですが、前のバージョンはダウンロード出来ない様です。実はこの最新バージョンはインストール時に .NET Framework3.5 を要求します。私の開発環境は、WIndows2000なので、そもそも.NET Framework3.5 自体インストールできません。そういう訳で、今回 Sandcastle Help File Builder の使用は見送りました。

では、まずは Sandcastle のインストールを行ないます。この時に環境変数 DXROOT が登録されます。実は、ここで2つ注意点があります。
1つは、環境変数に登録されるフォルダ名が、最後 \ 付きになっている事です。後々使用するバッチファイルや、xmlファイル等では、最後 \ 無しを前提にしているので、この環境変数の最後の \ は除去すべきです。手動で修正しましょう(最初私は、ここでつまづいた)。

2つめは、環境変数登録が有効になるのは、Windows 再起動後(再ログオンでもOK)なので、インストール後は、Windows を再起動(または再ログオン)しておいた方が良いでしょう。

Sandcastle インストールの次の作業として、普通は日本語でドキュメント生成したい筈ですから、ローカライズする必要があります。ここでも、最初見ていたところでは何も書いてなかったので、私はつまづいてしまいました。
ローカライズは、 TimberLandChapel さんのブログの「Sandcastle January 2008 のローカライズ」 からダウンロードして設定するのがいいでしょう。但しダウンロードには、サイトへのメンバ登録が必要です。なお、最新の対応バージョンは、May 2008 Release(Version 2.4.10520)です。June 2010 Release(Version 2.6.1062.1)に、そのまま対応出来るかは今のところ調査していません。(11/3 追記:そのままでは対応出来ません)

さて Sandcastle Help File Builder が使用出来ない状況なので、実際に使用するには、コマンドラインからの実行が必要です。そこで、バッチファイルを作成します。
(11/3:修正)といっても、実際は、%DXROOT%\Examples\sandcastle\build_Sandcastle.bat のバッチファイルを使用します。このバッチファイルを、ドキュメント生成したいアセンブリファイル及びXMLコメントファイルの存在するフォルダにコピーします。bnote の「Sandcastleでドキュメントを作成する」 からダウンロードしたバッチファイルを多少手直しして使用しました。

これでようやく、実行出来る環境が出来ました。実行するには、ドキュメント生成の対象となるソリューションとソース等の一式が必要です。とりあえず、シンプルな以下のクラスを用意して、XMLコメントファイルを生成する様にして、コンパイルしました。

using System;
using System.Collections.Generic;
using System.Text;
using System.Windows.Forms;

namespace VThink.test
{
    /// <summary>
    /// 金額入力テキストボックス
    /// </summary>
    public class CurrencyEdit : TextBox
    {
        /// <summary>
        /// 金額値を取得または設定する
        /// </summary>
        public int Value
        {
            get { return int.Parse(base.Text); }
            set { base.Text = Value.ToString(); }
        }
    }
}

ここに、前述の build_Sandcastle.bat ファイルをコピーしておきます。そしてコマンドプロンプトから、このフォルダをカレント状態にして、実行します。次の指定の様にして実行します。

build_Sandcastle.bat vs2005 CurrencyEdit

ちなみに、第1パラメータは、prototype / vs2005 / hana のうちどれかを指定します。これは作成されるヘルプの種類になります。第2パラメータは、アセンブリの名前です。
実行には、結構時間がかかります。のんびり待ちましょう。終了すると、ヘルプファイルが出来ます。しかし...うーん、期待通りとはいかなかった。
以下の図の様に、文字化けしてる部分があるし、サンプルに使用したコンポーネントクラスのXMLファイルの summary タグの内容すら反映されてないし、という事で原因を追求する必要が出て来ました。

これら不具合の原因は、...と言いたいところなのですが、すみません。1回で全部書きたかったのですが、調査に結構時間がかかってしまい、全部まとめていたのでは、今日中にアップできそうもありません。都合上、これ以降の続きは次回に持ち越します。

« 親コンテナを無効にしても子コントロールを灰色表示にしない方法 | トップページ | Sandcastle を使用したドキュメント作成(2) »

C#研究」カテゴリの記事

コメント

コメントを書く

コメントは記事投稿者が公開するまで表示されません。

(ウェブ上には掲載しません)

トラックバック


この記事へのトラックバック一覧です: Sandcastle を使用したドキュメント作成(1):

« 親コンテナを無効にしても子コントロールを灰色表示にしない方法 | トップページ | Sandcastle を使用したドキュメント作成(2) »