HDAにヘルプを付ける方法(Pythonスクリプトのおまけ付き)

この記事は[**Houdini Advent Calender 2019**](https://qiita.com/advent-calendar/2019/houdini)の8日目の記事です。

昨今、Houdiniは色んな業界でも使われるようになり、様々なHDAが各社で開発されてると思います。  
半面、管理やドキュメントの整備がされていないと**他人が作ったHDAの使い方が分からない、どういったHDAが存在するか把握できない**といった事態に陥ります。

この記事では下図のようなパラメータに対してのツールチップと独自のドキュメントを作成する方法を紹介します。

![NodeHelp](https://dl.dropboxusercontent.com/s/69seh4cmmzn5dl6/NodeHelp.gif?dl=0)

**<font color="crimzon">※なお私はWindows環境しか確認環境がないため、別のプラットフォームだとディレクトリなど若干違う箇所があるかもしれませんが、ご了承下さい。</font>**

# ヘルプを書く場所

ヘルプは下記の2箇所のどちらかに書く事が出来ます。

- **Type PropertiesウィンドウのHelpタブ**
- **$HOUDINI_PATH/help/nodes/カテゴリ/オペレータタイプ名.txt**

|![HelpTab.jpg](https://dl.dropboxusercontent.com/s/0u8e1o68b53c4re/HelpTab.jpg?dl=0)|![HelpFile.jpg](https://dl.dropboxusercontent.com/s/p14k85fxvkcm7cw/HelpFile.jpg)|
|---|---|
|Helpタブ|テキストファイル|

 
どちらに書くかはスタジオのやり方や好みによりますが、私はヘルプとHDAを別で管理したいため、テキストファイルを書いています。  
ちなみに標準ノードやGame Development Toolsetも同じ方法で管理されてます。  

Helpの書式は**Wikiマークアップ**を使用し、書くことが出来ます。詳しくは下記ドキュメントをご覧下さい。

- [Wikiマークアップリファレンス](https://www.sidefx.com/ja/docs/houdini/help/format.html)

ドキュメントをご覧いただくと分かりますが、このWikiマークアップによる書式はかなり高機能です。
しかしその分、慣れている方はともかく、そうでない方には若干敷居が高く感じます。
そういった方はHoudini標準ノードのヘルプソースを見ることが出来るので、そこから改変する方が良いと思います。

# 標準ノードのマークアップを見る

標準ノードのマークアップを見るには2通りのやり方があります。

- **パラメータエディタのヘルプボタンを押し、URL欄の最後に.txtを付ける。**
ソースを見たいノードを出し、パラメータエディタのヘルプボタンをクリックし、表示されるURL(しばらく待たないと適切に表示されません)の後ろに**\.txt**を追加することでそのノードのマークアップを見ることが出来ます。
![HelpBrowser.jpg](https://dl.dropboxusercontent.com/s/guy6wbsd09qjg2j/HelpBrowser.jpg?dl=0)

- **ローカルにあるテキストファイルを見る。**
ローカルのテキストファイルは**$HH/help/nodes.zip/カテゴリ/オペレータタイプ名.txt**に存在します。
<font color="crimzon">**※$HHはHoudiniインストールディレクトリ/houdiniです</font>(例:`C:/Program Files/Side Effects Software/Houdini 17.5.391/houdini`**)
![DefaultHelp.jpg](https://dl.dropboxusercontent.com/s/h1qvzig7yfeu7is/DefaultHelp.jpg?dl=0)

# アセットのヘルプでよく使う書式

ソースの見方が分かったところで、[Align Sop](https://www.sidefx.com/docs/houdini/nodes/sop/align.html)のソースを例にアセットの書式についてまとめておきます。　　
<img src="https://dl.dropboxusercontent.com/s/ktujui8ye2twfjk/HelpSample.jpg?dl=0">

1. タイトルです。<font color="crimzon">**=**</font>で囲みます基本的にオペレータラベルが書かれています。  

2. iconはノードのアイコンの設定で、それ以外の箇所はフィルタリングなどに使うための情報を記述で、ヘルプの見た目には影響しません。  

3. 要約。<font color="crimzon">**"""**</font>で囲みます。基本2行内で収まるような簡易な説明が書かれています。

4. ノードの目的とオペレーションの説明です。<font color="crimzon">**==**</font>で囲んで、タイトルを書き、改行して説明を書きます。

5. イメージの挿入。**../**は**$HOUDINI_PATH/help/**を表します。アニメーションgifを読み込む場合は<font color="crimzon">**[Anim:ファイルパス.gif]**</font>にします。

6. 入力による説明です。<font color="crimzon">**＠inputs**</font>で入力について説明したセクションを始めます。
各入力に対して入力のラベルの後にコロン(:)を書きます。
その下に入力に対するノードの挙動などをインデントを付けて記述します。

7. <font color="crimzon">**＠paramters**</font>でパラメータについて説明したセクションを始めます。
パラメータをフォルダで分けてる場合は<font color="crimzon">**== フォルダラベル ==**</font>にすることで分けることが出来ます。
パラメータにツールチップを設定していない場合、このパラメータの説明の第一段落を自動的に抽出して、それをパラメータのツールチップとして使用します。
**<font color="crimzon">#id:</font>**プロパティとパラメータ名を追加しなかった場合、そのパラメータのラベルを使ってパラメータのマッチングを試みます。
とはいえ、**<font color="crimzon">#id:</font>**プロパティをすべてのパラメータに追加する方が良いです。
そうすることで、いくつかのパラメータのラベルが重複していても、それらのパラメータは適切にリンクされます。

8. <font color="crimzon">**＠related**</font>で関連ページへのリンクのセクションを作成することができます。

**さらに詳しい説明は下記ドキュメントをご覧下さい。**

- [アセットのドキュメント作成](https://www.sidefx.com/ja/docs/houdini/help/nodes.html)

# カスタムサンプルの作成

ヘルプにカスタムサンプルを付けることも出来ます。サンプルを作成するには下記の2つのファイルを所定の場所に置く必要があります。

- **オブジェクトネットワークで作成した.hdaファイル**
- **サンプルの説明を書いたテキストファイル**

<font color="crimzon">**※.hdaファイルがオブジェクトネットワーク以外の場合、例えばDopならDop Networkを作成してオブジェクトネットワークに内包する必要があります。**</font>

上記2つのファイルは同じファイル名にして、下記ディレクトリに置きます。

- **$HOUDINI_PATH/help/examples/nodes/カテゴリ/オペレータタイプ名/**

例えば<font color="crimzon">**mynode**</font>というSopのHDAに<font color="crimzon">**MyNodeExample**</font>という名前のカスタムサンプルを表示する場合は下記にサンプルファイルを置きます。

- **$HOUDINI_PATH/help/examples/nodes/sop/mynode/MyNodeExample.hda**
- **$HOUDINI_PATH/help/examples/nodes/sop/mynode/MyNodeExample.txt**

ファイルが用意出来たら下記記述をヘルプに書き足すことでカスタムサンプルを表示させる事が可能です。

```
:load_example: My Node Example
    #examplefile: /examples/nodes/sop/mynode/MyNodeExample.hda
    #path: /examples/nodes/sop/mynode/MyNodeExample
    #include: yes
```

**カスタムサンプル例**
![カスタムサンプル例](https://dl.dropboxusercontent.com/s/0m0ahydcjmlw4mr/NodeExample.jpg?dl=0)

# スクリプトによる半自動化
ここまでドキュメントの作成方法を説明してきましたが、毎回これを設定するのはかなり面倒です。特にパラメータが多いHDAになるとかなりの労力が必要になってきます。  
そこで下図のパラメータのリストアップ、編集を行えるPythonスクリプトを使用し、ヘルプを書きやすいようにします。  

![Help Editor.gif](https://dl.dropboxusercontent.com/s/fiilusmm4sk5jnq/HelpEditor.gif?dl=0)

スクリプトは下記GitHubのリポジトリからダウンロードして使用することが出来ます。

- [Houdini Help Editor](https://github.com/TakashiKoide/HoudiniHelpEditor)

# まとめ
以上、HDAのヘルプの書き方とスクリプトの紹介でした。
もし記事内で間違いや不明点等あれば書き込んでいただけると幸いです。
最後までお読みいただき、ありがとうございました。

# 参考
SideFX公式ドキュメント(日本語版)

- [Wikiマークアップリファレンス](https://www.sidefx.com/ja/docs/houdini/help/format.html)
- [ヘルプの使い方](https://www.sidefx.com/ja/docs/houdini/help/index.html)
- [アセットのドキュメント作成](https://www.sidefx.com/ja/docs/houdini/help/nodes.html)
- [カスタムサンプルの作成](https://www.sidefx.com/ja/docs/houdini/help/createexamples.html)