In-tool Help

Developers can provide in-tool help for users that will be displayed in the GUI. There are several changes that need to be made to a channel in order to provide in-tool help. Node schemas need two additional attributes, the channel documentation directory needs to be updated, and markdown and image files need to be added for nodes,.

Schema Attributes

There are two schema attributes for in-tool help. Note that both of these attributes are optional. If they are not present in the schema then no help will be provided.

The 'help' attribute is a reference to a markdown file that provides help when the user clicks on the "i" symbol in the upper right corner of the node icon. This attribute is structured as follows: <package>/<markdown.md> where the 'package' is the name of the package containing the help file, and 'markdown.md' is the name of the markdown file.

The 'thumbnail' attribute is a reference to a PNG file that is an image to be displayed when the user hovers over the node name in the node tray. This attribute is structured as follows: <package>/<thumbnail.png> where 'package' is the name of the package containing the thumbnail, and 'thumbnail.png' is the name of the PNG file.

Here is an example of a schema that specifies both a help file and a thumbnail attribute.

  Tank:
    inputs: []
    outputs:
    - name: Generator
      description: Object generator
    tooltip: Abrams Tank AFV
    help: satrgb/Tank.md
    thumbnail: satrgb/Tank.png
    category: Generators
    color: "#cc1414"
    subcategory: AFV

The help file is called 'Tank.md' and it is stored in the 'satrgb' package. The thumbnail is 'Tank.png' and it is stored in the 'satrgb' package.

Channel Documentation Directory Changes

With this update we force channel developers to name their channel documentation file “channel.md“ that is included in the docs/ directory at the top-level of the channel. Other assets can be included in that docs/ directory and will be referenced from the channel.md file. File references are relative to the docs/ directory so subdirectories can be included if desired. An example is this snippet showing an example output image in the channel.md file.

![Example Output](output/image.png)

The image will be located in docs/output/image.png of the channel repository.

Channel Structure

The channel directory structure supports the inclusion of documentation assets. Here is an example of the structure:

docs/
  |- channel.md
  |- image1.png
packages/
  |- satrgb/
    |- satrgb/
      |- docs/
        |- __init__.py
        |- node1.md
        |- node1.png
        |- node2.md
        |- node2.png

The top-level docs directory contains the channel’s documentation file, channel.md along with any supporting assets required by the markdown file. The package documentation should be self-contained within the package, included in a packages///docs directory as mentioned above.

Note that the package docs directory must include an empty "__init__.py" file so that the Python package manager can find it.

Channel Deployment

The anadeploy process uses the anautils command to compile the documentation assets into a directory structure that can be used by the channel deployment service. The compiled assets directory looks like this:

docs/
  channel/
    |- channel.md
    |- image1.png
    |- video1.gif
  packages/
    |- anatools/
      |- docs/
    |- satrgb/
      |- docs/

Note the anautils command is automatically run by the anadeploy process so this information is for reference purposes only.

If there is something wrong with the documentation, such as a misspelled md or png file reference, then the channel deployment process will fail. It is a good idea to check the validity of your documentation before running anadeploy. To do this, you run the anautils command by hand as follows:

anautils --mode=help --output=/tmp/

This will check the validity of your links and compile the documentation into the temp directory. If there is something wrong with your documentation, you will receive an error message.