Overview

When you create templates or effects and want to share them, it might be useful to provide some documentation to future users.

The PopcornFX editor can automatically generate effect and template documentation for you.

It will analyze the effect, extract metadata, and use the descriptions of your nodes and template inputs to build an HTML documentation file.

It will highlight the contents of the effect interface (attributes, attribute samplers, outgoing events…), each public and local template, and detail all their inputs and outputs, their types, default values, data ranges, and more.

Any graph compilation messages (infos, warnings, or errors), are also listed:

Here is an example of the documentation generated for the “Trail” template, from the core template library:

Viewing and building documentation

From assets

When the editor is running, simply select an asset in the content browser, and hit “F1“, or right-click and select “Show documentation“.
This will open your default internet browser, to the documentation page of the file.

1. Show documentation: Open the documentation of this asset in the default web browser. Auto-generates the documentation if necessary.
2. Build documentation: Only generate the documentation file, without opening it.

The “Build documentation” menu will also appear when right-clicking on folders, and is useful to batch-build the documentation files for an entire project

The documentation files will be output by default in the “Documentation” folder at the root of your project, and will mirror the asset folder hierarchy.
You can change this default path in the project settings, under “Project > Documentation“.

From nodes

When in the effect editor, you can show the documentation of any template node.
In the nodegraph, select a node and hit “F1“, or right-click and select “Show Documentation“. This will open the documentation of that node in your default web browser.

You can also show the documentation of nodes from the effect treeview panel.

Customizing the documentation

Node descriptions

The documentation generator looks up each node’s “Description” property, and inserts that text as the description of nodes and template inputs.

You can use custom formatting in the “Description” text by using simple HTML markup tags.

For example, when setting the description of an “Axis” template input node to the following text:

Stretch axis
<b>This is an <font color=#F87>important</font> description!</b>

The nodal editor will display the following tooltip when hovering the “Axis” pin of that template:

And the documentation page will display the “Axis” input as follows:

Stylesheet

You can provide a custom stylesheet for the documentation generator to use per-project, in the project settings, under “Project > Documentation“.

Note that this is still work in progress, and we might change or break the current stylesheet. Please contact us if you plan to override the stylesheet.