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

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

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

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

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

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

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

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は、その設定を上書きするかどうかです。

プロキシサーバーをセットアップするには、以下の手順を踏みます:

1. 上記で説明しているようにhhelp serveを使ってヘルプサーバープロセスを起動します。

2. セントラルサーバー用ディレクトリを作成し、その中に、静的ファイル用ディレクトリを作成します:

   % mkdir central central/files
   % cd central
   

3. 静的ヘルプファイル(画像やスタイルシートなど)をcentral/filesディレクトリにコピーします。

   (一部のファイルは.zipファイルに圧縮されています。目的のファイルを指定してコピーするのは面倒なので、そのzipファイル内のすべてのファイルを1箇所にコピーします。)

   % mkdir files/icons files/images files/static
   % unzip $HFS/houdini/help/icons.zip -d files/icons
   % unzip $HFS/houdini/help/images.zip -d files/images
   % cp -r $HFS/houdini/help/videos videos
   % cp -r $HFS/houdini/python2.7libs/bookish/static/* static
   % cp -r $HFS/houdini/python2.7libs/houdinihelp/static/* static
   

   ($HFS/houdini/python2.7libs内のbookish/staticとhoudinihelp/staticの内容をcentral下のfiles/static単一ディレクトリにマージしていることに注意してください。)

4. centralディレクトリの絶対パスが設定された環境変数を作成します。

   例:

   export CENTRAL=/home/username/central
   

   (これは必ずしも必須ではありませんが、下記の例では便宜的にそのcentralのディレクトリパスを示した$CENTRALを使用しています。)

1. スタンドアローンのHTTPサーバーをインストールします。

   この手順は、あなたが使用したいHTTPサーバーに依存します。 私どもはnginxなどの軽量サーバーを推奨しています。

   システム上にサーバーソフトウェアをインストールする方法は、このドキュメントの範囲を超えています。 プラットフォーム別にサーバーソフトウェアをインストールする方法は、そのドキュメントを参照してください。 一般的に、Linuxでは、ディストリビューションのパッケージマネージャを使うことでnginxをインストールすることができます。 Macでは、まず最初にHomebrewをインストールしてから、そのHomebrewを使ってnginxをインストールすることができます。

2. HTTPサーバーが静的ファイルを直接提供し、他のリクエストをヘルプサーバーに中継させるようにセットアップします。

   これは、あなたが使用しているHTTPサーバーとその設定方法に大きく依存します。 以下の例を参照してください。

以下はnginxのコンフィグレーションファイルの例です。 このファイルをcentralディレクトリに保存することができます。

worker_processes 4;
daemon off;
error_log stderr;
http {
    include /usr/local/etc/nginx/mime.types;
    server {
        listen 0.0.0.0:9090;
        location ~ ^/(images|icons|videos|static)/ {
            root $CENTRAL/files;
        }
        location / {
            proxy_pass http://localhost:8080/;
        }
    }
}
events {
    worker_connections  1024;
}

(利用可能な設定の全リストは、nginxのドキュメントを参照してください。)

• この例では、サーバーが別プロセスを即座にフォークして返さないようにdaemon offを設定しているので、そのエラーメッセージと他の出力を確認することができます。目的通りにサーバーをセットアップすることができたら、サーバーがバックグラウンドで実行できるように、これをonに変更してください。 nginx -s reloadを使用すればそのコンフィグファイルをリロードすることができ、nginx -s stopを使用すればサーバーを停止することができます。

• include /usr/local/etc/nginx/mime.types;の行は、インストール方法によって異なります。 nginxのmime.typesファイルがインストールされている場所をチェックして、そのパスを指定してください。

• listen 0.0.0.0:9090の行には、nginxサーバーがリッスンするIPアドレス/ポートを設定します。 これは、ヘルプサーバーがリッスンしているポート(上記の例では8080)と 異なる ポートを設定してください。

  (localhostや127.0.0.1とは違って)0.0.0.0のリッスンは、ネットワーク上の他のコンピュータがこのサーバーにアクセスできることを意味します。

• root $CENTRAL/files;の行には、上記で作成したcentralディレクトリの絶対パスを指定してください。 このパスには、ホームディレクトリを意味するチルダ(~)を使用することが できません 。

• proxy_pass http://localhost:8080/;の行には、ヘルプサーバーのルートURLを指定してください。

このコンフィグレーションを使ってnginxを起動することができます:

% nginx -c $CENTRAL/proxy.nginx

コンフィグファイルの絶対パスを指定しなければならないことに注意してください。 絶対パスを指定しなかった場合、nginxは現行ディレクトリではなくてインストールディレクトリを基準にコンフィグファイルを検索します。 もう一度言いますが、このパスには、ホームディレクトリを意味するチルダ(~)を使用することができません。

これで、ブラウザにURLを指定することで、そのサーバーにアクセスすることができます:

http://localhost:9090/

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("$HFS/houdini/python2.7libs"))
   
   # 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をHTTPサーバーとして起動し、リッスンするアドレス/ポートを設定し、(上記でセットアップした)静的ファイルの提供元となるディレクトリを指定し、このアプリケーションのWSGI関数を生成するスクリプトの場所を指定します:

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

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

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

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

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

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

   hhelp generate files

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

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