Houdini 20.0 ヘルプの使い方

セントラルヘルプサーバーの実行

On this page

概要

スタジオにセントラルヘルプサーバーをセットアップすれば、マシン毎に各Houdiniが各自のヘルプサーバーを実行させることなく、 複数のHoudiniユーザにヘルプを提供することができるようになります。 これは、ユーザ間のサイト固有のドキュメントを共有するのに役立ちます。

Note

共有ネットワークからスタジオのカスタムアセットをユーザに提供している場合、 それぞれのHoudiniインスタンスは中央サーバーを必要とすることなく、そのアセットのヘルプをブラウズすることができます(ただし、そのアセットドキュメントをインデックス化する少しのCPU時間がすべてのマシンで重複します)。 ノードのドキュメント以外のドキュメントも一元管理したいのであれば、セントラルヘルプサーバーの方が便利です。

このドキュメントでは、フルでHoudiniを起動することなくHoudiniヘルプを用意するための方法をいくつか説明しています:

  • ヘルプサーバーを起動する方法。これは、Houdiniに同梱されているデフォルトのPythonサーバーを単に起動させるだけです。 これが最も簡単な選択肢であり、まず最初に試すべき方法です。 ユーザの数が多くてそれが十分でないことが分かったならば、以下のもっと高速な方法のどれかを使用すると良いでしょう。

  • WSGIアプリケーションサーバー内でHoudiniヘルプWSGIアプリを起動する方法。

  • 静的ヘルプを提供する方法。これは、ヘルプ内のwikiファイルから事前にHTMLファイルを生成するので、プレーンHTTPサーバーを使ってHTMLファイルを提供することができます。

    これが最も高速なソリューションで、プレーン静的ファイルを提供するだけなのでセットアップが簡単で、且つ、ライセンスのインストールが不要です。 このソリューションによって、Houdiniのヘルプを既存のウェブサーバーで公開することができます。 これは、動的コンテンツも検索もノードに埋め込まれたヘルプも 提供しません 。

ライセンス

ヘルプサーバーは、通常ではノードやツールに埋め込まれているヘルプを読み込むためにHOMを使用するので、起動するのにHoudiniライセンスが必要になります。

Apprenticeライセンスを含む任意の Houdiniライセンスを使ってhythonを実行することができます。 最も簡単な方法は、セントラルサーバーマシンをセットアップして、そこにApprenticeライセンスだけをインストールして、そのサーバープロセスがそのライセンスを使用するようにすることです。

他のライセンスタイプを不許可にすることで、 hythonがApprenticeライセンスを使用する ようにすることができます:

hhelp --skip-license-modes="commercial,indie,education" ...

静的ヘルプの提供にはライセンスは不要ですが、いくつか欠点があることに注意してください。 詳細は、下記の静的ヘルプの提供を参照してください。

デフォルトのヘルプサーバーを起動する

セントラルヘルプサーバーのセットアップの最も簡単な方法は、Houdiniに同梱されているデフォルトのPythonサーバーを単に起動させることです。 この欠点は、このPythonサーバーは単一プロセスしか使用できず、Pythonコードを使ってすべてのファイル(画像、スタイルシートなど)を提供していることです。 これは、中小規模のスタジオだと十分な速さかもしれませんが、ユーザが増えれば、アプリケーションサーバーを使用する方法または静的ファイルを提供する方法を調査する必要が出てきます。

  • セットアップが簡単。

Tip

このドキュメントの以前のバージョンでは、ヘルプを高速化するためにプロキシサーバーを使用することを推奨していましたが、 今では、Houdini/hythonはネイティブコードを使用して静的ヘルプファイル(アイコンや画像など)を提供するようになったので、 ページの読み込みが大幅に高速化され、多数のユーザにサービスを提供するために複数のサーバースレッド/プロセスが必要にならない限り、プロキシサーバーを起動する必要性はおそらくありません。

コマンドライン

  1. Houdiniシェルを開きます。

    Windows

    スタート ▸ すべてのプログラム ▸ Side Effects Software ▸ Houdini X.X.XXX ▸ Utilities ▸ Command line tools をクリックします。

    Mac

    ファインダーから Applications ▸ Houdini ▸ HoudiniX.X.X ▸ Utilities ▸ Houdini Terminal を開きます。

    Linux

    bashシェルで、cdでHoudiniインストールディレクトリに移動し、source houdini_setupをタイプします。

  2. Houdiniシェルで、以下をタイプします:

    hhelp --skip-license-modes="commercial,indie,education" serve --host=0.0.0.0 --port=8080 -bgindex=true

    これは、バックグラウンドのインデックス化を有効にしてヘルプサーバーを立ち上げます。

  3. ブラウザを開いて、以下のURLにアクセスします。

    http://localhost:8080/

serveコマンド

--host=0.0.0.0

サーバーのIPアドレス。

  • コンピューターに複数のネットワークコントローラーがあれば、ヘルプサーバーにListenさせたいアドレスを指定することができます。

  • ヘルプサーバーを他のコンピュータから利用可能にするには、0.0.0.0(デフォルト)を使用します。

  • ヘルプサーバーをあなたのコンピュータでのみ利用可能にするには、localhostまたは127.0.0.1を使用します。

--port=8080

サーバーのポート番号。デフォルトは8080です。

--debug

情報のデバッグを有効にして、サーバーを実行します。

--bgindex

サーバーが実行中にバックグラウンドで変更のあったドキュメントのインデックスを再生成します。

--config=path

(オプション) コンフィグオプションを読み込むファイル。

--logfile=path

(オプション) サーバーログの書き出し先のファイル。

--loglevel=DEBUG|INFO|WARNING|ERROR

(オプション) この重要度レベルでメッセージをログにします。

indexコマンド

このコマンドは、手動で検索インデックスを更新します(--bgindexオプションでサーバーを実行していない場合)。デフォルトでは、このコマンドは--cleanオプションを指定しない限り、変更のあったファイルのみを更新します。

hhelp --skip-license-modes="commercial,indie,education" index

--clean

ドキュメントの変更の有無に関わらず、ゼロからすべてのドキュメントのインデックスを再生成します。

--usages

サンプルファイルで使用されているノードに関する情報を生成します。

--config=path

(オプション) コンフィグオプションを読み込むファイル。

--logfile=path

(オプション) サーバーログの書き出し先のファイル。

--loglevel=DEBUG|INFO|WARNING|ERROR

(オプション) この重要度レベルでメッセージをログにします。

hython内でコードからサーバーを起動する方法

(hython内で)コードでビルトインのサーバーを起動したい場合:

from houdinihelp.server import start_server

start_server(
    host="0.0.0.0",         # Listenするネットワークインターフェース
    port=8080,              # Listenするポート
    debug=False,            # サーバーをデバッグモードで実行させるかどうか
    bgindex=None ,          # バックグラウンドインデックスを行なうかどうか
    config_file=None,       # コンフィグファイルまでの文字列パス
    use_houdini_path=True,  # 以下を参照してください
)

  • config_fileがNoneでuse_houdini_pathがTrueの場合には、そのコードはhouを使用して、Houdiniパスからconfig/Help/bookish.cfgコンフィグファイルを検索します(以下のコンフィグを参照してください)。これはhouがまだインポートされていない時にバッチライセンスを使用します。その引数にコンフィグファイルを指定していれば、このことについて心配する必要はありません。

  • bgindexキーワード引数には、True, False, Noneを指定することができます。Noneは、設定ファイルの値を使用し、TrueまたはFalseは、その設定を上書きするかどうかです。

Houdiniクライアントがセントラルサーバーを使用するように設定する方法

一度セントラルサーバーをセットアップしてしまえば、Houdiniクライアントは、自身のローカルヘルプサーバーを起動することなく、そのセントラルサーバーからヘルプを取得するように設定することができます。

  • Houdini UIにて:

    1. メインメニューから Edit ▸ Preferences ▸ Miscellaneous を選択します。

    2. Use External Help Server を有効にします。

    3. External Help URL にセントラルサーバーのURL(例えば、http://server.local:8080/houdini/)を設定します。

    または

  • UIを使用しないでスタジオ全体で変更を行ないたいのであれば、$HOUDINI_USER_PREF_DIR/houdini.pref内に直接misc.useexternalhelp.val := 1とmisc.externalhelpurl.val := "help_url"のキーを使用することで、そのプリファレンスを設定することができます。

WSGIアプリケーションサーバーを使用する方法

上記のプロキシサーバーの例は、hhelpを使っていつものHoudiniヘルプサーバーを起動してから必要に応じてヘルプサーバーにリクエストを転送することができるので比較的セットアップが簡単です。

しかし、この欠点は、HTTPを介してヘルプサーバーと通信するには幾分非効率であり、そのPythonヘルプサーバーは単一プロセス/単一スレッドで処理能力が限定されます。

ヘルプサーバーを起動してリクエストをそのサーバーに転送する方法とは違って、このソリューションは、uwsgi、gunicorn、modwsgiによるApacheなどの WSGIアプリケーションサーバー を使用して、Houdiniヘルプのアプリケーションコード自体を実行するので、マルチプロセス/マルチスレッドで処理をすることができます。

WSGIは、スタンドアローンのHTTPサーバーがPython関数を実行して動的なウェブコンテンツを生成可能にするプロトコルです。 この欠点は、そのサーバーが通常のPythonインタープリタ自体を起動する必要があるので、Houdiniのライブラリのパスが自動的にセットアップされたhythonに頼ることができないことです。 このセクションに載せているapplication.pyは、Houdiniヘルプアプリケーションが通常のPythonを実行できるようにPythonパスを制御します。

  • 通常のヘルプサーバーよりも高速です。

  • 指定したディレクトリから動的なwikiヘルプを提供することができます。

  • houを使用することができないので、この方法では、アセットまたはツールに埋め込まれているヘルプを提供することができません。

  • (Houdiniのライブラリが使用できるように自動的にPythonパスをセットアップする)hythonを使用することができないのでセットアップが若干難しいです。

重要事項:

  • HoudiniヘルプアプリケーションはアプリケーションサーバーからHOMを使用することができないので、ノード内部のヘルプを提供することができません。 この方法を使用するには、ノードのヘルプはアセット内部に埋め込むのではなく、ディスク上のファイルとして保存する必要があります。

  • $HFS変数などの環境変数が利用できるようにするために、Houdiniシェル環境内でサーバーを起動してください。

  • このドキュメントでは、一般的なソリューションと設定について説明します。 一部のソリューションでは、サードパーティ製ソフトウェアのインストールと設定が必要になります。 このドキュメントには、いくつか例が含まれていますが、残念ながら、プラットフォーム、ソフトウェア、設定オプションの有り得るすべての組み合わせが網羅されていることは期待できません。 使用するソフトウェア、その設定オプション、あなたが選んだソフトウェアがWSGIなどの規格をどのように使用するのかは、あなた独自で調べる必要があります。

アプリケーションサーバーをセットアップする方法

  1. まず最初に、セントラルサーバーディレクトリのセットアップのとおりにディレクトリ構造をセットアップします。

    以下のようなディレクトリ構造にしてください:

    central/
    files/
        icons/
            ...
        images/
            ...
        videos/
            ...
        static/
            ...

  2. アプリケーションサーバーでは、サーバーページをコールするapplication()関数を生成するスクリプトが必要です。

    アプリケーションサーバーは、hythonではなくPythonを使ってスクリプトを実行するので、Houdiniライブラリが自動的に利用可能になりません。

    以下の例のスクリプトは、Houdiniのライブラリが見つかるようにPythonパスを制御し、application()関数を生成する前にアプリケーションが$HFS下のファイルを見つけられるように設定します。

    これをcentral下にapplication.pyという名前のファイルに保存します。

    central/application.pyスクリプトの例

    import logging
import sys
from os.path import expandvars

# PythonパスにHoudiniライブラリを追加します。
sys.path.append(expandvars("$HHP"))

# Houdiniのサードパーティ製Pythonライブラリを追加します。残念ながら、このパスはプラットフォーム依存です。
if sys.platform in ("linux", "linux2"):
   sys.path.append(expandvars("$HFS/python/lib/python2.7/site-packages-forced"))
elif sys.platform == "darwin":
    sys.path.append(
        expandvars(
            "$HFS/Frameworks/Python.framework/Versions/Current/lib/python2.7/site-packages-forced"
        )
    )
elif sys.platform in ("win32", "win64"):
    sys.path.append(expandvars("$HFS/python27/lib/site-packages-forced"))


from houdinihelp.hconfig import HoudiniHfsConfig
from houdinihelp.server import get_houdini_app


class MyConfig(HoudiniHfsConfig):
    # 提供元となるディレクトリ
    DOCUMENTS = [
        # $HFS/houdini/help下にあるファイルを"展開"(Zip解凍)します。
        expandvars("$HFS/houdini/help"),
        {
            # これは、$HFS/houdini/help内の.zipファイルからドキュメントを読み込めるようにします。
            "type": "object",
            "classname": "bookish.stores.ZipTree",
            "args": {
                "dirpath": expandvars("$HFS/houdini/help"),
            }
        },
        # これは、ユーザープリファレンスディレクトリ内のhelpディレクトリ下のファイルを追加します。
        expandvars("$HOUDINI_USER_PREF_DIR/help"),

        # サーバーに追加したい他のディレクトリをここに追加します。
        # "/my/dir",
    ]

    # ユーザープリファレンスディレクトリ内にキャッシュを保存します。
    CACHE_DIR = expandvars("$HOUDINI_USER_PREF_DIR/config/Help/cache")

    # Houdiniに同梱されているフルテキストインデックス。
    # バックグラウンドインデックスを使用したいのであれば、このディレクトリを書き込み可能な場所にコピーして、
    # その書き込み可能ディレクトリのパスをここに設定してください。
    INDEX_DIR = expandvars("$HFS/houdini/config/Help/index")

    # サーバーがバックグラウンドでインデックス化スレッドを実行するようにさせたいのであればTrueを設定します。
    ENABLE_BACKGROUND_INDEXING = False
    # バックグラウンドインデックスが実行される間隔の秒数。
    BACKGROUND_INDEXING_INTERVAL = 60

    # houを使用しないページマネージャを指定します。
    PAGES_CLASS = "houdinihelp.hpages.HoudiniPagesWithoutHou"


application = get_houdini_app(
    use_houdini_path=False,
    config_obj=MyConfig,
    loglevel=logging.INFO,
    debug=False,
)

  3. WSGIアプリケーションサーバーをインストールします。

    この手順は、あなたが使用したいアプリケーションサーバーに依存します。 私どもはuwsgiなどの軽量サーバーを推奨しています。

    システム上にサーバーソフトウェアをインストールする方法は、このドキュメントの範囲を超えています。 プラットフォーム別にサーバーソフトウェアをインストールする方法は、そのドキュメントを参照してください。 uwsgiに関しては、Pythonのpip3パッケージマネージャ(pip3 install uwsgi)を使ってインストールすることができます。 これは、基本プログラムだけでなく必要なすべてのプラグインもインストールされるので、uwsgiに最適なインストール方法です。

  4. WSGIアプリケーションサーバーが静的ファイルを直接提供し、application.pyスクリプトを使って動的なヘルプページを提供するようにセットアップします。

    これは、あなたが使用しているアプリケーションサーバーとその設定方法に大きく依存します。 WSGI機能の扱い方と静的ディレクトリの指定方法の詳細は、あなたのアプリケーションサーバーのドキュメントを参照してください。

uwsgiの例

以下のコマンドは、uwsgiをHTTPサーバーとして起動し、リッスンするアドレス/ポートを設定し、(上記でセットアップした)静的ファイルの提供元となるディレクトリを指定し、このアプリケーションのWSGI関数を生成するスクリプトの場所を指定します:

% uwsgi --http 0.0.0.0:9090 --check-static $CENTRAL/files $CENTRAL/application.py

静的ヘルプを提供する方法

  • 最速で最も堅牢なソリューションです。

  • どのHTTPサーバーも使用することができ、アプリケーションの設定が不要です。

  • Houdiniライセンスが不要です。

  • 静的ページのみを提供し、動的wikiページは提供しません(つまり、wikiヘルプファイルを編集してもブラウザでリロードしてその結果を即座に確認することができません)。

  • 検索機能なし!

すべてのヘルプファイルを事前生成する

  1. まず最初に、上記のセントラルサーバーディレクトリのセットアップのとおりにディレクトリ構造をセットアップします。

    以下のようなディレクトリ構造にしてください:

    central/
    files/
        icons/
            ...
        images/
            ...
        videos/
            ...
        static/
            ...

  2. Houdiniシェルで、cdコマンドを使ってcentralディレクトリに移動します。

  3. 以下のコマンドを実行します:

    hhelp generate files

    これは、Houdiniヘルプ内のすべてのwikiファイルから静的なHTMLファイルを生成します。 これには時間がかかります。

  4. 一度HTMLファイルを生成すれば、どのHTTPサーバーでもcentral/files内のファイルを提供するようにすることができます。

ヘルプサーバーの設定

  • hhelpコマンドラインユーティリティで--configオプションを使ってコンフィグレーションファイルを指定することができます。 または、houdinihelp.server.get_houdini_appやhoudinihelp.server.start_serverのconfig_fileパラメータを使ってコード内でコンフィグレーションファイルを指定することもできます。

  • コンフィグレーションファイルを指定しない、且つ、HOUDINIPATH/config/Help/bookish.cfgが存在する場合、(use_houdini_path=Falseを渡さない限り)サーバーはそのファイルを読みに行きます。

  • ヘルプサーバーはFlaskベースです。Flaskのコンフィグレーションファイルは実際はPythonです。

例えば、$HOME/myfilesにあるファイルのディレクトリを追加するには、コンフィグレーションファイルに以下のステートメントを追加します:

EXTRA_DOCUMENTS = ["$HOME/myfiles/"]

役に立ついくつかのコンフィグレーションキーは、以下を参照してください。

役に立つコンフィグレーションキー

DOCUMENTS = [...]

ドキュメントソースのデフォルトのリストには、Houdiniパスのhelpディレクトリ、さらには、アセットとシェルフツール内部のヘルプの読み込みを可能にする特別なソースが含まれています。 このリストを、ディレクトリ のみ を提供できるようにディレクトリパスのリストに置換することができます。例:

DOCUMENTS = ["/my/dir"]

置換の代わりに、コンフィグレーションファイル内でこのリストを拡張することもできますが、その場合、EXTRA_DOCUMENTSを使用した方が簡単です(以下参照)。

EXTRA_DOCUMENTS = []

デフォルトのDOCUMENTSに加える“追加”ドキュメントソースのリスト。 これは、デフォルトのドキュメントだけでなく、いくつか追加でディレクトリを提供したい時に役立ちます。

(このデフォルトのリストにはHOUDINIPATH/helpが含まれているので、Houdiniパスを拡張することでも同様の事ができます。)

EXTRA_DOCUMENTS = ["/my/dir"]

ENABLE_BACKGROUND_INDEXING = False

変更のあったコンテンツの再インデックス化をするためにバックグラウンドでスレッドを実行するかどうかを指定します。 これは、コマンドラインの--bgindexオプションで上書きすることができます。

BACKGROUND_INDEXING_INTERVAL = 60

バックグラウンドインデックスが有効な時に再インデックス化する間隔の秒数。

EXTRA_SHORTCUTS = []

検索ショートカットを参照してください。

CACHE_DIR = "$HOUDINI_USER_PREF_DIR/config/Help"

wikiソースファイルから生成された.jsonファイルをサーバーがキャッシュ化する場所。

INDEX_DIR = "$HFS/houdini/config/Help/index"

検索インデックスを含んだディレクトリ。

ヘルプの使い方

基本

ノードのドキュメント化

セントラルヘルプサーバーの起動