Houdini 17.0 How to use the help

Running a central help server

On this page

Overview

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. This is useful for sharing site-specific documentation between users.

See also wiki markup reference, how to document your assets, and how to make example files.

Warning

The default server setup imports the hou package, meaning it uses a batch license when run outside of Houdini. See how to not use a batch license below for a work-around.

Command line

  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 serve --bgindex=true
    

    …to start the help server with background indexing.

  3. Open a browser and go to

    http://localhost:8080/
    

hhelp serve

--host=0.0.0.0

The IP address for the server.

  • If your computer has multiple network controllers, you can specify which address you want the server to listen at.

  • Use 0.0.0.0 (the default) to make the server available to other computers.

  • Use localhost or 127.0.0.1 to make the server only available on your computer.

--port=8080

The port number for the server. Default is 8080.

--debug

Run the server with debugging information on.

--bgindex

Re-index changed documents in the background while the server is running.

--config=path

(Optional) a file to read configuration options from.

--logfile=path

(Optional) a file to write server log to.

--loglevel=DEBUG|INFO|WARNING|ERROR

(Optional) log messages at or above this level of severity.

hhelp index

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.

--clean

Re-index all documents from scratch, whether they've changed or not.

--usages

Generate information about what nodes are used by example files.

--config=path

(Optional) a file to read configuration options from.

--logfile=path

(Optional) a file to write server log to.

--loglevel=DEBUG|INFO|WARNING|ERROR

(Optional) log messages at or above this level of severity.

In Python

If you have Houdini’s Python libraries in your PYTHONPATH, you can get the Houdini WSGI app for use in an application server (for example, Apache with ModWSGI):

from houdinihelp.server import get_houdini_app

wsgi_app = get_houdini_app(
    config_file=None,       # Path string to a config file
    use_houdini_path=True,  # See below
    log_file=None,          # If not None, overrides default log file path
    log_level=None          # If not None, overrides default log level    
)

To start the built-in server instead:

from houdinihelp.server import start_server

start_server(
    host="0.0.0.0",         # Network interface to listen to
    port=48626,             # 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.

Serving Houdini docs from your server

You can serve the WSGI application on your server. For example, you can serve the app through ModWSGI on Apache, or by reverse-proxying an instance of uWSGI running the app.

Configuration

  • You can specify a configuration file in the hhelp command line utility using the --config option, or in code using the config_file parameter of houdinihelp.server.get_houdini_app or houdinihelp.server.start_server.

  • If you don’t specify a configuration file and HOUDINIPATH/config/Help/bookish.cfg exists, the server will load it (unless you pass use_houdini_path=False).

  • The help server is based on Flask. Flask’s configuration files are actually Python.

For example, to add a directory of files at $HOME/myfiles, put the following in the configuration file:

EXTRA_DOCUMENTS = ["$HOME/myfiles/"]

See below for some useful configuration keys.

Useful configuration keys

DOCUMENTS = [...]

The default list of document sources includes help directories from the Houdini path, as well as special sources that allow reading help from inside assets and shelf tools. You can replace this with a list of directory paths to serve only your directories. For example:

DOCUMENTS = ["/my/dir"]

It’s possible to extend this list in your configuration file instead of replacing it, but in that case it’s easier to use EXTRA_DOCUMENTS (see below).

EXTRA_DOCUMENTS = []

A list of "extra" document sources to be added on to the defaults in DOCUMENTS. This is useful when you want the defaults but also want to serve from some additional directories

(Note that the default list includes the HOUDINIPATH/help, so you can extend the Houdini path to achieve the same thing.)

EXTRA_DOCUMENTS = ["/my/dir"]

ENABLE_BACKGROUND_INDEXING = False

Whether to run a thread to re-index changed content in the background. Overridden by the --bgindex option on the command line.

BACKGROUND_INDEXING_INTERVAL = 60

The number of seconds between re-indexes when background indexing is on.

EXTRA_SHORTCUTS = []

CACHE_DIR = "$HOUDINI_USER_PREF_DIR/config/Help"

Where the server caches .json files generated from wiki source files.

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

Directory containing the search index.

Configuring a central server to not use a batch license

The default server uses hou for certain functionality:

  • Looking for a configuration file on the Houdini path.

  • Adding HOUDINIPATH/help, nodes, and shelf tools to the list of document sources.

  • Indexing example files.

To prevent the server from using a batch license, you need to:

  • Create a configuration file for the server.

  • In the configuration file replace the default list of document sources, and change the default PAGES_CLASS configuration key.

  • Create a script to start the server using regular Python. (Starting the server using hhelp or hython will automatically import hou and use a license).

Using this configuration file will disable functionality that relies on hou:

  • You will not be able to read read help from the Help tab of nodes and shelf tools.

  • Help links and references to opdef: will not work.

  • Indexing example files.

How to run the help server without a license

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 http://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/"]
    

How to use the help

Basics

Documenting nodes

Running a central help server