Using Houdini with an external help server

A studio can set up a central help server to serve help to multiple users of Houdini, instead of each instance of Houdini starting up its own help server on each machine.

There are two main tasks to setting up a central Houdini help server:

1. Create a central help server.

2. Re-index the help.

3. Start the help server process.

4. Change the settings in each user’s Houdini to use the central server instead of its own.

Open the command line tools. (on Windows, choose Start > Side Effects Software > Houdini X.X.XXX > Command Line Tools, on Linux source the Houdini environment).

1. Choose the computer with Houdini installed and create a directory to hold the customized server files.

   cd $HOME
   mkdir helpserver
   cd helpserver
   

2. Add the $HH/scripts/pythonlibs and $HH/scripts/python directories to the PYTHONPATH environment variable. For example, in a Linux BASH shell:

   export PYTHONPATH=$PYTHONPATH:$HH/scripts/pythonlibs:$HH/scripts/python
   

3. Create a directory to hold the search index. For example, in Linux:

   mkdir index
   

4. Copy the help server configuration file that comes with Houdini into your server directory:

   cp $HH/config/Help/deploy.ini deploy.ini
   

5. Edit the deploy.ini file to match your local configuration.

   • Set the index option to the path of the directory you created for the search index.

   • Set the docs option to a comma separated list of directories to search for help content.

     If you're running a central help server, you likely just want to change this line to:

     docs = $HH/help, /path/to/my/help/tree
     

     To overlay the contents of your custom help directory tree over the original Houdini help.

   • Set the host option to the IP address of the server computer.

   • Set the port option to the port number the web server should run on.

   • Set the threadpool_workers and threadpool_spawn_if_under options to larger numbers. This will increase the thread pool size of your server making it more efficient at handling requests from multiple machines. A threadpool_workers value of 10 and a threadpool_spawn_if_under value of 5 are good starting points.

In the server .ini file, in the [app:exampleloader] section is an exampleprefix option. This value is prepended to example resource paths, such as /examples/nodes/dop/clothsolver/AnimatedClothPatch.otl. The default value of $HFS/houdini/help points to the location of the examples shipped with a Houdini install.

This prefix value does not allow a list of multiple paths, but it can be an HTTP URL. If you want to create your own examples, you will need to do one of the following:

• Change exampleprefix to the URL of the help server. For example, http://innisfail:5050/. This will make Houdini load the examples from the server over HTTP.

  With the exampleprefix option set to a URL, you can use the docs option to overlay your own directory of examples over the default examples that ship with Houdini.

  Note

  Houdini can load OTL examples directly using the URL. Older .cmd examples will be downloaded to a temp file and then sourced locally. This means .cmd examples that rely on external files (such as textures or data files) will break.

Or…

• Copy the example file tree ($HFS/houdini/help/examples/...) to a central location available over a network file share (such as NFS or Windows file sharing). Then change exampleprefix to a network share path available to all clients.

  After you copy the “factory” example files to a central location and set the help server’s exampleprefix to that location, you can add your own example files to that location.

  [app:exampleloader]
  paste.app_factory = houdinihelp.wsgi:exampleloader_factory
  exampleprefix = /nfs/central/help
  

  On a heterogeneous network where each client OS needs the network share path in a different format, you can set up an environment variable on each client machine to point to the correct share path for that client’s platform, then use the environment variable in the exampleprefix setting:

  [app:exampleloader]
  paste.app_factory = houdinihelp.wsgi:exampleloader_factory
  exampleprefix = $CENTRAL_SERVER/help
  

  Alternatively, you can use separate exampleprefixLinux, exampleprefixWindows, and exampleprefixMac options. For example:

  [app:exampleloader]
  paste.app_factory = houdinihelp.wsgi:exampleloader_factory
  exampleprefixLinux = /nfs/central/help
  exampleprefixWindows = \\central\help
  

“Indexing” the help creates a directory containing information necessary to display and search the help. Each time you change, add to, or delete from your custom help, you need to “re-index” to make those changes visible to the search.

1. In the command line tools shell, go to your help server directory.

2. Make sure you changed the index configuration option in deploy.ini. You don’t want to overwrite the index in $HFS.

3. Type the following:

   python $HH/scripts/python/index.py deploy.ini
   

   This will iterate over the text files in the directories listed in the docs configuration option and add/update them in the search index.

   Normally this script only updates the search information for new files and files that have changed or been deleted since the last time you ran the script. To force the script to index everything from scratch, use:

   python $HH/scripts/python/index.py deploy.ini --clean
   

python $HH/scripts/python/server.py deploy.ini

You can type python $HH/scripts/python/server.py --help for a list of options.

You may want to create a wrapper script to allow starting and stopping the server as a background process.

• An alternative way to integrate the Houdini help into an existing web server is to run the help server along the main server and simply redirect certain URLs on the main web server to the help server. The Python web server is small and certainly not as fast or robust as Apache, but it should be fast enough to handle hundreds of users comfortably.

To set up Houdini’s embedded browser to use an external help server:

1. Start Houdini.

2. Choose Edit > Preferences > Miscellaneous.

3. Turn on Use external help server.

4. In the External help URL field, enter the URL of the external help server.

   For example, if you started a central server on port 5050 on a computer named innisfail, you would enter

   http://innisfail:5050/

   …as the external help URL.

Houdini’s help pages are written in a wiki format that is translated into HTML by the server.

To write pages in wiki format, create a text file (with the extension .txt) with wiki formatted text (see wiki formatting). For example, if the docs configuration file is set to:

docs = $HH/help, /myhelp

Then you can create the file /myhelp/mypage.txt and have it show up in the browser as /mypage. (If you open http://localhost:5050/mypage.txt in a browser, you’ll see the wiki text. If you open http://localhost:5050/mypage or http://localhost:5050/mypage.html, you’ll see the HTML generated from the wiki text.)