この記事はHoudini Advent Calender 2019の8日目の記事です。

昨今、Houdiniは色んな業界でも使われるようになり、様々なHDAが各社で開発されてると思います。

半面、管理やドキュメントの整備がされていないと他人が作ったHDAの使い方が分からない、どういったHDAが存在するか把握できないといった事態に陥ります。

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

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

ヘルプを書く場所

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

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


Helpタブ	テキストファイル

どちらに書くかはスタジオのやり方や好みによりますが、私はヘルプとHDAを別で管理したいため、テキストファイルを書いています。

ちなみに標準ノードやGame Development Toolsetも同じ方法で管理されてます。

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

Wikiマークアップリファレンス

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

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

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

パラメータエディタのヘルプボタンを押し、URL欄の最後に.txtを付ける。
ソースを見たいノードを出し、パラメータエディタのヘルプボタンをクリックし、表示されるURL(しばらく待たないと適切に表示されません)の後ろに.txtを追加することでそのノードのマークアップを見ることが出来ます。
ローカルにあるテキストファイルを見る。
ローカルのテキストファイルは$HH/help/nodes.zip/カテゴリ/オペレータタイプ名.txtに存在します。
※$HHはHoudiniインストールディレクトリ/houdiniです(例:C:/Program Files/Side Effects Software/Houdini 17.5.391/houdini)

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

ソースの見方が分かったところで、Align Sopのソースを例にアセットの書式についてまとめておきます。　　

タイトルです。=で囲みます基本的にオペレータラベルが書かれています。
iconはノードのアイコンの設定で、それ以外の箇所はフィルタリングなどに使うための情報を記述で、ヘルプの見た目には影響しません。
要約。"""で囲みます。基本2行内で収まるような簡易な説明が書かれています。
ノードの目的とオペレーションの説明です。==で囲んで、タイトルを書き、改行して説明を書きます。
イメージの挿入。../は$HOUDINI_PATH/help/を表します。アニメーションgifを読み込む場合は[Anim:ファイルパス.gif]にします。
入力による説明です。＠inputsで入力について説明したセクションを始めます。
各入力に対して入力のラベルの後にコロン(:)を書きます。
その下に入力に対するノードの挙動などをインデントを付けて記述します。
＠paramtersでパラメータについて説明したセクションを始めます。
パラメータをフォルダで分けてる場合は== フォルダラベル ==にすることで分けることが出来ます。
パラメータにツールチップを設定していない場合、このパラメータの説明の第一段落を自動的に抽出して、それをパラメータのツールチップとして使用します。
#id:プロパティとパラメータ名を追加しなかった場合、そのパラメータのラベルを使ってパラメータのマッチングを試みます。
とはいえ、#id:プロパティをすべてのパラメータに追加する方が良いです。
そうすることで、いくつかのパラメータのラベルが重複していても、それらのパラメータは適切にリンクされます。
＠relatedで関連ページへのリンクのセクションを作成することができます。

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

アセットのドキュメント作成

カスタムサンプルの作成

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

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

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

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

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

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

$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

カスタムサンプル例

スクリプトによる半自動化

ここまでドキュメントの作成方法を説明してきましたが、毎回これを設定するのはかなり面倒です。特にパラメータが多いHDAになるとかなりの労力が必要になってきます。

そこで下図のパラメータのリストアップ、編集を行えるPythonスクリプトを使用し、ヘルプを書きやすいようにします。

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

Houdini Help Editor

まとめ

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

参考

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

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

ヘルプを書く場所

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

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

カスタムサンプルの作成

スクリプトによる半自動化

まとめ

参考