Sandcastle Help File Builder による ヘルプドキュメント作成...
Transcript of Sandcastle Help File Builder による ヘルプドキュメント作成...
![Page 1: Sandcastle Help File Builder による ヘルプドキュメント作成 …yujiro15.net/YKSoftware/download/150406_SandcastleHelpFileBuilder.pdfYK Software SHFB : Sandcatsle Help](https://reader031.fdocuments.net/reader031/viewer/2022041612/5e3876d14a3b2f0982451f4b/html5/thumbnails/1.jpg)
YK S o f t w a r e
Sandcastle Help File Builder による
ヘルプドキュメント作成方法
2015 年 2 月 5 日
Yujiro15
![Page 2: Sandcastle Help File Builder による ヘルプドキュメント作成 …yujiro15.net/YKSoftware/download/150406_SandcastleHelpFileBuilder.pdfYK Software SHFB : Sandcatsle Help](https://reader031.fdocuments.net/reader031/viewer/2022041612/5e3876d14a3b2f0982451f4b/html5/thumbnails/2.jpg)
YK Software
プロフィール
1 / 20
2009 年
2010年
2013年
2014年
プログラミング経験
Excel VBA
MATLAB, MATX
VC++(MFC)
VC++(Windows SDK)
Yujiro15
1982/03/03 生まれ(うお座)
A 型
左利き(お箸は右)
WPF + C#
C++ で開発、WPF + C# でデバッグ
某メーカーに入社 4 月
1 月~
8 月
4 月~
PLC ラダーを勉強する
C で開発、MFC でデバッグ
C++ で開発、MFC でデバッグ
WPF + C# という素晴らしいツールに出会う
WPF + C# を勉強する
Web Site : http://yujiro15.net/YKSoftware/
![Page 3: Sandcastle Help File Builder による ヘルプドキュメント作成 …yujiro15.net/YKSoftware/download/150406_SandcastleHelpFileBuilder.pdfYK Software SHFB : Sandcatsle Help](https://reader031.fdocuments.net/reader031/viewer/2022041612/5e3876d14a3b2f0982451f4b/html5/thumbnails/3.jpg)
YK Software
背景
2 / 20
自作クラスライブラリのヘルプドキュメントを作成したいんだけど…
Microsoft Office (Word 等)で作成する
UML ツール(Enterprise Architect 等)で作成する
Visual Studio の XML ドキュメントコメントを活用する
変更の度に見直しが必要。手間がかかる上にモレる。
クラス図だけならいいかも。
XML ファイルが出力される。将来性あり?
構造図は得意だが、説明書的なドキュメントに向かない。
独自のスタイルで好きなように編集できる。
コードに直接書くので変更も同時に編集できる。
![Page 4: Sandcastle Help File Builder による ヘルプドキュメント作成 …yujiro15.net/YKSoftware/download/150406_SandcastleHelpFileBuilder.pdfYK Software SHFB : Sandcatsle Help](https://reader031.fdocuments.net/reader031/viewer/2022041612/5e3876d14a3b2f0982451f4b/html5/thumbnails/4.jpg)
YK Software
XML ドキュメントコメントの活用 (1/2)
3 / 20
Visual Studio の XML ドキュメントコメント
/// <summary> /// This is class performs an important function. /// </summary> public class MyClass { }
3 つのスラッシュでコメントフィールドになる
ビルドオプションを設定すると
XML ファイルとして出力できる
https://msdn.microsoft.com/ja-jp/library/b2s063f7.aspx
MSDN C# プログラミングガイド
![Page 5: Sandcastle Help File Builder による ヘルプドキュメント作成 …yujiro15.net/YKSoftware/download/150406_SandcastleHelpFileBuilder.pdfYK Software SHFB : Sandcatsle Help](https://reader031.fdocuments.net/reader031/viewer/2022041612/5e3876d14a3b2f0982451f4b/html5/thumbnails/5.jpg)
YK Software
XML ドキュメントコメントの活用 (2/2)
4 / 20
出力される XML ファイル
<?xml version="1.0"?> <doc> <assembly> <name>YKToolkit</name> </assembly> <members> <member name="T:YKToolkit.ComboBoxWindowFunctions"> <summary> Math.WindowFunctions 選択用列挙体表示用クラス </summary> </member> <member name="…
決められたタグで整形された XML コード
これを見れる形にするには?
・XSD ファイルで定義
開発工数がハンパない
・他人のソフトに頼る 時にはこういった割り切りも重要
![Page 6: Sandcastle Help File Builder による ヘルプドキュメント作成 …yujiro15.net/YKSoftware/download/150406_SandcastleHelpFileBuilder.pdfYK Software SHFB : Sandcatsle Help](https://reader031.fdocuments.net/reader031/viewer/2022041612/5e3876d14a3b2f0982451f4b/html5/thumbnails/6.jpg)
YK Software
SHFB : Sandcatsle Help File Builder
5 / 20
元々は Microsoft が作成していた Sandcastle という CUI だった
現在は SHFB として開発が継続されている (現時点で最終更新は 2015.1.12)
GitHub からダウンロードしてインストールしましょう!
https://github.com/EWSoftware/SHFB
![Page 7: Sandcastle Help File Builder による ヘルプドキュメント作成 …yujiro15.net/YKSoftware/download/150406_SandcastleHelpFileBuilder.pdfYK Software SHFB : Sandcatsle Help](https://reader031.fdocuments.net/reader031/viewer/2022041612/5e3876d14a3b2f0982451f4b/html5/thumbnails/7.jpg)
YK Software
SHFB インストールの注意点
6 / 20
通常のプロジェクトと同様に
ソリューションツリーに SHFB のプロジェクトを作成することができる
ソフトウェア変更 ヘルプファイル変更 の流れが非常に容易になる
Visual Studio に SHFB の
パッケージをインストール
すること!!
![Page 8: Sandcastle Help File Builder による ヘルプドキュメント作成 …yujiro15.net/YKSoftware/download/150406_SandcastleHelpFileBuilder.pdfYK Software SHFB : Sandcatsle Help](https://reader031.fdocuments.net/reader031/viewer/2022041612/5e3876d14a3b2f0982451f4b/html5/thumbnails/8.jpg)
YK S o f t w a r e
SHFB プロジェクトの導入
![Page 9: Sandcastle Help File Builder による ヘルプドキュメント作成 …yujiro15.net/YKSoftware/download/150406_SandcastleHelpFileBuilder.pdfYK Software SHFB : Sandcatsle Help](https://reader031.fdocuments.net/reader031/viewer/2022041612/5e3876d14a3b2f0982451f4b/html5/thumbnails/9.jpg)
YK Software
サンプルクラスライブラリ (1/2)
8 / 20
namespace SampleLibrary
{
/// <summary> /// あれをこれするためのクラスです。
/// </summary>
public class Class1
{
/// <summary> /// 名前を取得または設定します。
/// </summary>
public string Name { get; set; }
/// <summary> /// 値を取得します。
/// </summary> /// <param name="index">インデックスを指定します。 /// <returns>これこれの値</returns>
public int GetValue(int index)
{
return 0;
}
}
}
コメントフィールドを挿入しておく
![Page 10: Sandcastle Help File Builder による ヘルプドキュメント作成 …yujiro15.net/YKSoftware/download/150406_SandcastleHelpFileBuilder.pdfYK Software SHFB : Sandcatsle Help](https://reader031.fdocuments.net/reader031/viewer/2022041612/5e3876d14a3b2f0982451f4b/html5/thumbnails/10.jpg)
YK Software
サンプルクラスライブラリ (2/2)
9 / 20
XML ドキュメントを出力するようにしておく
![Page 11: Sandcastle Help File Builder による ヘルプドキュメント作成 …yujiro15.net/YKSoftware/download/150406_SandcastleHelpFileBuilder.pdfYK Software SHFB : Sandcatsle Help](https://reader031.fdocuments.net/reader031/viewer/2022041612/5e3876d14a3b2f0982451f4b/html5/thumbnails/11.jpg)
YK Software
SHFB プロジェクトの追加
10 / 20
"Documentation" というツリーが追加されています
![Page 12: Sandcastle Help File Builder による ヘルプドキュメント作成 …yujiro15.net/YKSoftware/download/150406_SandcastleHelpFileBuilder.pdfYK Software SHFB : Sandcatsle Help](https://reader031.fdocuments.net/reader031/viewer/2022041612/5e3876d14a3b2f0982451f4b/html5/thumbnails/12.jpg)
YK Software
Documentation Sources の設定
11 / 20
右クリックで Source を追加する
dll でも csproj ファイルでも可
![Page 13: Sandcastle Help File Builder による ヘルプドキュメント作成 …yujiro15.net/YKSoftware/download/150406_SandcastleHelpFileBuilder.pdfYK Software SHFB : Sandcatsle Help](https://reader031.fdocuments.net/reader031/viewer/2022041612/5e3876d14a3b2f0982451f4b/html5/thumbnails/13.jpg)
YK Software
とりあえずコンパイルしてみる (1/2)
12 / 20
コンパイル時の注意
ターゲットの XML ファイルがないと正常に生成できない
必ず SHFB 以外のプロジェクトを先にコンパイルする
プロジェクトフォルダの "Help" フォルダに .chm ファイルが生成される
コンパイルすると
![Page 14: Sandcastle Help File Builder による ヘルプドキュメント作成 …yujiro15.net/YKSoftware/download/150406_SandcastleHelpFileBuilder.pdfYK Software SHFB : Sandcatsle Help](https://reader031.fdocuments.net/reader031/viewer/2022041612/5e3876d14a3b2f0982451f4b/html5/thumbnails/14.jpg)
YK Software
とりあえずコンパイルしてみる (2/2)
13 / 20
そのままビルドするとこんな感じ
タイトル
ドキュメントタイトル
更新履歴
Getting Started
そもそもこのツリー構成でいいのかどうかも含めて修正が必要
デフォルト設定なので色々直さないといけないところがある
![Page 15: Sandcastle Help File Builder による ヘルプドキュメント作成 …yujiro15.net/YKSoftware/download/150406_SandcastleHelpFileBuilder.pdfYK Software SHFB : Sandcatsle Help](https://reader031.fdocuments.net/reader031/viewer/2022041612/5e3876d14a3b2f0982451f4b/html5/thumbnails/15.jpg)
YK S o f t w a r e
SHFB プロジェクトの設定方法
![Page 16: Sandcastle Help File Builder による ヘルプドキュメント作成 …yujiro15.net/YKSoftware/download/150406_SandcastleHelpFileBuilder.pdfYK Software SHFB : Sandcatsle Help](https://reader031.fdocuments.net/reader031/viewer/2022041612/5e3876d14a3b2f0982451f4b/html5/thumbnails/16.jpg)
YK Software
Project Properties の設定 (1/2)
15 / 20
ファイル名
タイトル
言語選択
念のためですが、
.NET Framework のバージョンに注意
バージョンの確認
出力ファイルの種類を選択
お好みでチェックを外す
ここでは chm の作成をおこないます
![Page 17: Sandcastle Help File Builder による ヘルプドキュメント作成 …yujiro15.net/YKSoftware/download/150406_SandcastleHelpFileBuilder.pdfYK Software SHFB : Sandcatsle Help](https://reader031.fdocuments.net/reader031/viewer/2022041612/5e3876d14a3b2f0982451f4b/html5/thumbnails/17.jpg)
YK Software
Project Properties の設定 (2/2)
16 / 20
ファイル名
タイトル
言語選択
ツリータイトル等に日本語を使用する場合は
言語選択で "Japanese (Japan)" を選択すること
しないと文字化けます。
正式な対応はないのかなぁ…。
![Page 18: Sandcastle Help File Builder による ヘルプドキュメント作成 …yujiro15.net/YKSoftware/download/150406_SandcastleHelpFileBuilder.pdfYK Software SHFB : Sandcatsle Help](https://reader031.fdocuments.net/reader031/viewer/2022041612/5e3876d14a3b2f0982451f4b/html5/thumbnails/18.jpg)
YK Software
ContentLayout.content の設定 (1/2)
17 / 20
始めに表示するページとして指定されている
このツリーがそのまま反映される。
ダブルクリックするとそのファイルの
内容を編集できる。 ページのタイトル
例えばこれをダブルクリックすると…
ヘルプのページが
ツリー形式で表示されている
![Page 19: Sandcastle Help File Builder による ヘルプドキュメント作成 …yujiro15.net/YKSoftware/download/150406_SandcastleHelpFileBuilder.pdfYK Software SHFB : Sandcatsle Help](https://reader031.fdocuments.net/reader031/viewer/2022041612/5e3876d14a3b2f0982451f4b/html5/thumbnails/19.jpg)
YK Software
ContentLayout.content の設定 (2/2)
18 / 20
Introduction
ページ内容の編集
Getting Started
ツリーにページを追加したり、aml ファイルを編集したり…
![Page 20: Sandcastle Help File Builder による ヘルプドキュメント作成 …yujiro15.net/YKSoftware/download/150406_SandcastleHelpFileBuilder.pdfYK Software SHFB : Sandcatsle Help](https://reader031.fdocuments.net/reader031/viewer/2022041612/5e3876d14a3b2f0982451f4b/html5/thumbnails/20.jpg)
YK Software
カスタマイズ例
19 / 20
タイトル
ドキュメントタイトル
更新履歴
Getting Started はいらない
他にも Visual Studio のオフラインヘルプ形式にしたり html 形式にしたり…
どの形式が良いか検討してからカスタマイズしましょう
![Page 21: Sandcastle Help File Builder による ヘルプドキュメント作成 …yujiro15.net/YKSoftware/download/150406_SandcastleHelpFileBuilder.pdfYK Software SHFB : Sandcatsle Help](https://reader031.fdocuments.net/reader031/viewer/2022041612/5e3876d14a3b2f0982451f4b/html5/thumbnails/21.jpg)
YK Software
まとめ
20 / 20
Sandcatsle Help File Builder を導入した
・Visual Studio の XML ドキュメントコメントを修得した
・Visual Studio の XML ファイル生成方法を修得した
・SHFB によるヘルプファイル生成方法を修得した
・SHFB によるヘルプファイル編集方法を修得した
・Visual Studio プロジェクトをドキュメント化する手段を構築できた
参考 URL
https://github.com/EWSoftware/SHFB
http://dobon.net/vb/dotnet/vs/commentwebreport.html
DOBON.NET プログラミング道
EWSoftware / SHFB 公式 GitHub
バックグラウンドとして
https://msdn.microsoft.com/ja-jp/library/b2s063f7.aspx
MSDN C# プログラミングガイド
![Page 22: Sandcastle Help File Builder による ヘルプドキュメント作成 …yujiro15.net/YKSoftware/download/150406_SandcastleHelpFileBuilder.pdfYK Software SHFB : Sandcatsle Help](https://reader031.fdocuments.net/reader031/viewer/2022041612/5e3876d14a3b2f0982451f4b/html5/thumbnails/22.jpg)
YK S o f t w a r e
ご清聴ありがとうございました