[SandCastle] C#のxmlコメントからヘルプファイル(.chm)を作成する

**もくじ**
→https://qiita.com/tera1707/items/4fda73d86eded283ec4f

# やりたいこと

`SandcastleHelpFileBuilder`というものを使ってマニュアル(ヘルプファイル)を作っているライブラリがあり、そのマニュアル作成のための環境を作るということをしたので、その際のメモを残す。

下記のような、そのDLLで使用できるAPIの一覧と説明を記載したもの(.chmファイル)ができるイメージ。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/d964dfea-1c18-292c-f241-57d1032bf9c3.png)


# 手順

## SandcastleHelpFileBuilderをダウンロード

下記からダウンロードする。
https://github.com/EWSoftware/SHFB/releases
今回は`v2020.3.6.0`を使用（VisualStudio2019でも使える）

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/239937ec-f589-87fa-5eb8-81b3f4ddfc89.png)

zipをダウンロード
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/bf5441e8-8d2e-3a26-4c66-fcb91a579524.png)

## インストール

SandcastleInstaller.exeをたたいてインストール
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/a1499316-272f-3049-02ec-ebfc89594182.png)

Sandcastle Help File Builder and Toolsが表示されるまでNextを押す
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/ac2d82cd-5dc2-f1d3-eeca-6e2a166412e5.png)

Install SHFBを押す
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/74e4eda6-cf20-1f5e-d13c-49ade6ff10ae.png)

案内の通り、標準のままNext押していく
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/545a8c71-07a7-f6d1-a030-03867a7124a8.png)

SHFBインストール 完
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/abfcfca3-7b4d-3856-d2e9-0d9b55c24723.png)
ここにインストールされたらしい。NEXT押す。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/d09ed974-e2d8-1e9f-6944-894a89b69530.png)

VS2017,2019でつかえるようにするためのパッケージを入れる。
InstallPackageを押し、案内の通りにインストールする
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/82604e85-7f3a-7b1a-fbcd-cdbf0eb88248.png)

Vsix Installerがでてくるので、言われた通りインストールしていく。
終わったらNext。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/bec032a6-2532-1112-3369-df56aeb2de9c.png)


今のところ、コメントは手書きで全部書くので、この機能は使わなさそうのためinstallせずNext。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/be4e086b-6edb-f9f1-a3f3-dd52c5dacdd0.png)

これも同様。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/4048fed7-280e-da4b-1bd8-06a97fdd77d1.png)

次へ。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/af14ab68-bddd-b7cd-e0bb-6b275283c6a5.png)

次へ。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/45efaa16-9b48-9312-0dd5-8a028e573973.png)

インストール作業は完了。PCを再起動する。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/37597788-7ee3-bf0a-dacb-1498b198609f.png)


## VS上の作業

ドキュメントを作成したいC#のDLLのプロジェクトのプロパティを開き、
[ビルド] > [出力] の欄の[XMLドキュメントファイル] にチェックを入れる。
(パスはデフォルトでOK)
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/5331ae4a-6da9-51bd-6791-401ab32cef25.png)

それでビルドすると、ドキュメント用xmlが、出力先フォルダに生成される。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/7a571a6f-a9b5-2011-c4ac-8d23c24bff5c.png)


ドキュメントを作成したいC#のDLLのプロジェクトを含むソリューションを、VisualStudioのソリューションエクスプローラで右クリックし、新規プロジェクトの追加を選択する。
[プロジェクトの種類]から[Documentation]を選択、それで出てきた[Sand Castle HelpFile Buidler]を選んで決定する。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/ba90a065-2e36-c90b-c994-dd901dc1f6dd.png)

Documentのプロジェクトが作成される
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/e8e25344-5f83-1fa1-9f4e-470d3071be61.png)

Documentation Sourcesを右クリックし、Add Documentation Sourceを選ぶ
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/1677ab3b-9086-9cab-bfb0-fe03212fa7f3.png)

ドキュメントを作成したいC#のDLLの、出力されたdllを選択する。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/68cda804-3d9f-5a4f-421d-3398ab7fb545.png)

あとは任意で、プロジェクトの設定を好きに変える。
(以下、個人の趣味で変えたとこだけ)

ドキュメントの.chmファイルの出力先を好きなところにする。
(ドキュメントのプロジェクトの場所を基準に、相対パスOK。)
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/9d1648c2-b867-fa7c-03d3-d121502857c5.png)

デフォルトではC++などにもチェックが入っているが、C#だけでよいのでC#のみにチェックする。
今回欲しいのは`.chm`のヘルプファイルのみなので、`HTML Help1（chm）`にチェックを入れる。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/53727f62-85f3-0a5c-2ceb-ab3a9d2433e2.png)

`Help File name`が、chmファイルの名前に、`Help title`が、ヘルプウインドウのタイトルになる。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/751db3f4-5296-3f91-1641-b67929b7d63f.png)
ウインドウのタイトル
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/efc55935-b05f-bac1-964f-07afe4d68cf6.png)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/172f8f76-2a3b-f926-582f-7aa9d659f181.png)

protectedのメンバとか、その他もろもろとりあえずいらない奴は外しておく。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/25808e1e-27ca-5bf1-6177-362dd0c79a90.png)

Contentフォルダの中に`Welcome.aml`というファイルがあり、そこにヘルプファイルを開くと最初に表示されるWelcomeページの記述がある。
そのWelComeページの中身は、下の方にあるContentLayout.contentファイルをいじるといろいろ変えれるっぽいが、今回はそういうことはせず、DLLの仕様だけchmでわかればよいので削除して割愛。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/ac049484-4871-603a-82ef-439fc7815c10.png)

最終的に下記のように構成を間引いた。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/b8f81b76-c77d-23ba-f193-f4c6b2e77243.png)

出力ファイルは下記。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/8e4de368-4780-8106-7a26-57ad2e4d68b1.png)

こんな感じで出力された。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/352601/d964dfea-1c18-292c-f241-57d1032bf9c3.png)
コメントをちゃんと書いてないのでエラー表示になってるが、ちゃんと書けばちゃんと出るはず。


# 参照

Sandcastle(XMLコメントからAPIヘルプ生成)
ほぼこちらに書いている内容を参考にさせて頂きました。ありがとうございます。
https://blog.nextscape.net/research/dotnetenv/sandcastle

サンドキャッスルのgithubページ
https://github.com/EWSoftware/SHFB

サンドキャッスルのRelease版ダウンロードページ
https://github.com/EWSoftware/SHFB/releases