The help server normally requires a Houdini license to run, since it uses HOM to read help embedded in nodes and tools.

You can run hython with any Houdini license, including an Apprentice license. The easiest thing to do is set up a central server machine and install just an Apprentice license on it, so the server process will use that.

You can ensure hython uses an Apprentice license by disallowing the other license types:

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

Note that serving static help does not require ongoing use of a license, but has some drawbacks. See serving static help below for more information.

1. Open a Houdini shell.

   Windows

   Click Start ▸ All programs ▸ Side Effects Software ▸ Houdini X.X.XXX ▸ Utilities ▸ Command line tools.

   Mac

   In the Finder, open Applications ▸ Houdini ▸ HoudiniX.X.X ▸ Utilities ▸ Houdini Terminal.

   Linux

   In a bash shell, cd to the Houdini install directory and source houdini_setup.

2. In the Houdini shell, type:

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

3. Open a browser and go to

   http://localhost:8080/
   

This command lets you manually update the search index (if you're not running a server with the --bgindex option). By default the command will only update changed files, unless you pass the --clean option.

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

If you want to start the built-in server in code (in hython):

from houdinihelp.server import start_server

start_server(
    host="0.0.0.0",         # Network interface to listen to
    port=8080,             # Port to listen to
    debug=False,            # Whether to start the server in debug mode
    bgindex=None ,          # Whether to do background indexing
    config_file=None,       # String path to a config file
    use_houdini_path=True,  # See below
)

• If config_file is None and use_houdini_path is True, the code will use hou to search the Houdini path for a config/Help/bookish.cfg configuration file (see configuration below). This will use a batch license if hou hasn’t already been imported. If you're specifying a configuration file in the arguments you don’t need worry about this.

• The bgindex keyword argument can be True, False, or None. None means use the value from the configuration, whereas passing True or False will override the configuration.

1. First, set up the directory structure as in setting up central server directories.

   This should give you a directory structure like this:

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

2. The app server will require a script to create an application() function it will call to serve pages.

   The application server will run the script using Python, not hython, so it won’t automatically have the Houdini libraries available.

   The following example script manipulates the Python path so it can find Houdini’s libraries, and configures the application to find files under $HFS, before creating the application function.

   Save this to a file under central called application.py.

   Example central/application.py script

   import logging
   import sys
   from os.path import expandvars
   
   # Add Houdini libraries to Python path
   sys.path.append(expandvars("$HHP"))
   
   # Add Houdini's third-party Python libraries. Unfortunately this path is
   # platform-specific
   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):
       # The directories you want to serve from
       DOCUMENTS = [
           # "Loose" (unzipped) files under $HFS/houdini/help
           expandvars("$HFS/houdini/help"),
           {
               # This adds ability to read docs out of .zip files in
               # $HFS/houdini/help
               "type": "object",
               "classname": "bookish.stores.ZipTree",
               "args": {
                   "dirpath": expandvars("$HFS/houdini/help"),
               }
           },
           # This adds files under the help dir in your user prefs
           expandvars("$HOUDINI_USER_PREF_DIR/help"),
   
           # Add any other directories you want to add to the server here
           # "/my/dir",
       ]
   
       # Store the cache in the user's prefs dir
       CACHE_DIR = expandvars("$HOUDINI_USER_PREF_DIR/config/Help/cache")
   
       # The full-text index shipped with Houdini. If you want to use background
       # indexing, copy this directory somewhere writable, and set this to the path
       # of the writable directory.
       INDEX_DIR = expandvars("$HFS/houdini/config/Help/index")
   
       # True if the server should run an indexing thread in the background
       ENABLE_BACKGROUND_INDEXING = False
       # Number of seconds between background indexing runs
       BACKGROUND_INDEXING_INTERVAL = 60
   
       # Specify a page manager that doesn't use hou
       PAGES_CLASS = "houdinihelp.hpages.HoudiniPagesWithoutHou"
   
   
   application = get_houdini_app(
       use_houdini_path=False,
       config_obj=MyConfig,
       loglevel=logging.INFO,
       debug=False,
   )
   

3. Install a WSGI application server.

   This step is specific to the server you want to use. We recommend a lightweight server such as uwsgi.

   How to install server software on your system is beyond the scope of this document. See the instructions for your chosen server for how to install it on different platforms. For uwsgi, you can install it using Python’s pip3 package manager (pip3 install uwsgi). This is the best installation method for uwsgi since it installs all necessary plugins as well as the base program.

4. Set up your HTTP server to serve the static files directly, and use the application.py script to serve dynamic help pages.

   This is highly specific to the app server you use and how you want to configure the server. See the documentation for your application server for details of how it works with a WSGI function, and how you specify static directories.

The following command runs uwsgi as an HTTP server, sets the listening address/port, specifies the directory to serve static files from (as set up above), and points to the script that creates the application’s WSGI function:

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

1. First, set up the directory structure as in setting up central server directories above.

   This should give you a directory structure like this:

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

2. In Houdini shell, cd to the central directory.

3. Run the following command:

   hhelp generate files

   This will generate a static HTML file from every wiki file in the Houdin help. This can take a long time.

4. Once you have generated the HTML files, you can point any HTTP server to serve the files in central/files.