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.

This procedure assumes an install of Houdini on the computer you want to run the server on. While it’s technically possible to copy all the required files out of Houdini, it’s beyond the scope of this document and will not be supported. It’s much easier and more convenient to just use an installation, including a free Apprentice installation.

1. Run the server from a Houdini shell (so environment variables like $HFS are available).

   You can get a Houdini shell environment by starting the shell from the utility included with Houdini.

   Mac

   Applications/Houdini/Current/Utilities/Houdini Terminal X.X.X

   Windows

   Start menu > Side Effects Software > Command Line Tools X.X.X

   Linux

   cd to the Houdini install directory and run source ./houdini_setup.

   Or, just set the $HFS variable in your environment.

2. Use the following script to start. Remember to run the script using regular Python 2.7 (not hython).

   import argparse
   import sys
   from os.path import expandvars
   
   # Add Houdini libraries to Python path
   sys.path.append(expandvars("$HFS/houdini/python2.7libs"))
   
   # 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 HoudiniAppConfig
   from houdinihelp.server import get_houdini_app
   
   
   class MyConfig(HoudiniAppConfig):
       # 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"),
           # Any other directories you want to add to the server...
           "/my/dir",
       ]
   
       # Store the cache in the user's prefs dir
       CACHE_DIR = expandvars("$HOUDINI_USER_PREF_DIR/config/Help")
   
       # The full-text index to use
       INDEX_DIR = expandvars("$HFS/houdini/config/Help/index")
   
       # Specify a page manager that doesn't use hou
       PAGES_CLASS = "houdinihelp.hpages.HoudiniPagesWithoutHou"
   
   
   if __name__ == "__main__":
       parser = argparse.ArgumentParser(description="Starts bookish help server")
       parser.add_argument("--host", metavar="HOSTNAME", default="0.0.0.0",
                           help="IP address to serve on.")
       parser.add_argument("--port", metavar="NUM", type=int, default=8888,
                           help="Port number to serve on.")
       parser.add_argument("--config", metavar="FILE", default=None,
                           help="Configuration file to override defaults.")
       parser.add_argument("--log", metavar="FILE", default=None,
                           help="File to output the log to.")
       parser.add_argument("--loglevel", default="INFO",
                           help="The verbosity of the log: DEBUG, INFO, WARNING, or ERROR.")
       args = parser.parse_args()
   
       app = get_houdini_app(
           use_houdini_path=False,
           config_obj=MyConfig,
           config_file=args.config,
           logfile=args.log,
           loglevel=args.loglevel,
           debug=False,
       )
   
       app.run(host=args.host, port=args.port, threaded=True)
   

   (If Python complains that it can’t import houdinihelp, check that the path to Houdini’s libraries is correct. If it complains it can’t import flask, check that the path to the third-party libraries is correct.)

3. After you run the script, open a browser application (such as Chrome or Safari) and try to access https://localhost:8888/.

4. This is a simple example script which lets you set the hostname and port on the command line, but hard-codes directories and other options.

   Depending on your needs, you can edit the script to get more options (such as the hostname and port) from command line options (see the documentation for Python’s argparse module).

   You can also override options using a configuration file. For example, start the script above with a configration file argument:

   python runserver.py --config /Users/matt/helpserver.cfg
   

   Then in that file, you can override options:

   EXTRA_DOCUMENTS = ["/path/to/my/help_dir/"]