Skip to content

README.md

Latest commit

 

History

History
executable file
·
298 lines (225 loc) · 9.79 KB

README.md

File metadata and controls

executable file
·
298 lines (225 loc) · 9.79 KB

OFX Documentation

This is the documentation directory for OFX, the open visual effects standard.

Documentation Architecture

The OpenFX documentation system combines several tools:

  1. Doxygen - Parses C/C++ header files in the include directory to extract API documentation from comments
  2. Breathe - A Sphinx extension that bridges Doxygen XML output with Sphinx
  3. Sphinx - Processes ReStructured Text (.rst) files and Doxygen output to generate the final HTML documentation
  4. Python scripts - scripts/gen-props.py generates C++ metadata headers; scripts/gen-props-doc.py generates RST reference pages from inline metadata in the headers

The documentation is organized into:

  • Reference manual - API documentation generated from Doxygen comments in the header files
  • Guide - Tutorial content with examples in ReStructured Text
  • Release notes - Version-specific information

Building Docs

Buildthedocs.io will auto-build whenever changes are pushed to master. But to build the docs yourself, e.g. to check that your updates look right, you can do your own doc build.

Prerequisites

  • Install doxygen (Linux: sudo apt install doxygen)
  • Create a python3 virtualenv: python -mvenv ofx-docgen (may need to do apt install python3.8-venv first)
  • Activate it: source ofx-docgen/bin/activate
  • Install the python requirements in that virtualenv (e.g. Sphinx): pip install -r Documentation/pipreq.txt

(Virtualenv is recommended, but not required; you could install the reqs into your system python if you like.)

Build Process

The simplest way to build the documentation is to run the build script:

cd Documentation
./build.sh

This script performs the following steps:

  1. Generates property and property-set RST reference pages from inline @propdef/@propset metadata using scripts/gen-props-doc.py
  2. Builds Doxygen documentation from the header files (using include/doxy-filter.sh to strip metadata blocks)
  3. Uses Breathe to collect Doxygen API docs
  4. Builds the final HTML documentation with Sphinx

After building, you can view the documentation at: file:///path/to/your/ofx/openfx/Documentation/build/index.html

If you want to run the steps manually, you can follow the steps in build.sh.

Documentation Writing Guide

Doxygen Documentation

Doxygen is used to document C/C++ code in the source and headers. The main Doxygen configuration is in include/ofx.doxy.

Key Doxygen Features Used in OpenFX

  • Groups - Organize related items together

    /** \defgroup PropertiesAll Property Suite */
/** \ingroup PropertiesAll */
/** \addtogroup PropertiesAll @{ ... @} */

  • Documentation Comments - Document functions, structs, defines, etc.

    /**
 * \brief Brief description
 *
 * Detailed description that can span
 * multiple lines
 *
 * \param paramName Description of parameter
 * \return Description of return value
 */

  • Cross-references - Link to other documentation elements

    /** See \ref kOfxImageEffectPropSupportedPixelDepths */

ReStructured Text (RST) Documentation

RST files are used for the prose documentation in the /Documentation/sources directory.

Key RST Features Used in OpenFX

  • Section Headers - Create hierarchy with underlines

    Section Title
============

Subsection Title
---------------

  • Internal Links - Create references between sections

    .. _target-name:

Section Title
============

See :ref:`target-name` for more information.

  • Code Blocks - Display code examples

    .. code-block:: c

   #define kOfxImageEffectPluginRenderThreadSafety "OfxImageEffectPluginRenderThreadSafety"

  • Including Files - Embed external file content

    .. literalinclude:: ../examples/basic.cpp
   :language: cpp
   :lines: 10-20

  • Doxygen Integration - Include Doxygen-documented items

    .. doxygendefine:: kOfxImageEffectPropSupportsMultiResolution

.. doxygenfunction:: OfxGetPropertySet

.. doxygenstruct:: OfxRectD
   :members:

  • Cross-domain References - Link to C/C++ elements

    :c:macro:`kOfxImageEffectPropSupportsOverlays`
:cpp:class:`OfxImageEffectStruct`
:c:struct:`OfxRectD`
:c:func:`OfxGetPropertySet`

Breathe Integration

The Breathe extension bridges Doxygen and Sphinx, enabling:

  • Automatic generation of API documentation pages
  • Full cross-referencing between RST and Doxygen content
  • Consistent styling across all documentation

Documentation Maintenance Tips

  1. Common Issues

    • Missing cross-references - Check spelling of target names
    • Doxygen parse errors - Check comment formatting
    • Breathe integration issues - Check Doxygen XML output

  2. Adding New Documentation

    • For new API elements: Add Doxygen comments to header files
    • For new concepts/guides: Create new RST files in sources/Guide
    • For property references: They're automatically generated from inline metadata in headers (see below)

  3. Testing Changes

    • Always build documentation locally before submitting changes
    • Check for warning messages during the build process
    • Review the HTML output to ensure proper formatting and cross-references

Property and Action Metadata

Properties, property sets, and actions are documented using inline YAML metadata blocks embedded in doxygen comments in the C header files (include/ofx*.h). These blocks are parsed by scripts/gen-props.py (to generate C++ metadata headers) and scripts/gen-props-doc.py (to generate RST reference pages). A doxygen input filter (include/doxy-filter.sh) strips them from the doxygen output so they don't appear in the API reference HTML.

@propdef — Property Definitions

A @propdef block goes inside the /** ... */ doxygen comment for a property #define. It must appear at the end of the comment, just before the closing */. Everything before @propdef is treated as the doxygen documentation; everything after it is parsed as YAML.

/** @brief Unique name of the plug-in.

    - Type - C string X 1
    - Property Set - host descriptor (read only)
    - Valid Values - the unique name of the plug-in

    @propdef
    type: string
    dimension: 1
*/
#define kOfxPropName "OfxPropName"

Supported YAML fields:

Field Description Example
type Property type string, int, double, pointer, bool, enum
dimension Number of values (integer or N) 1, 2, N
values List of valid enum/string values ["false", "true", "needed"]
default Default value "false", 0
introduced Version when this property was added "1.4"
deprecated Version when this property was deprecated "1.4"
cname Override the C macro name (rare, for misnamed props) kOfxImageEffectFrameVarying

@propset — Property Set Definitions

A @propset block defines which properties belong to a named property set (e.g., the set of properties on an image effect descriptor). These are standalone /** ... */ comments, not attached to a #define.

/** @propset EffectDescriptor
    write: plugin
    props:
      - OfxPropLabel
      - OfxPropShortLabel
      - OfxPluginPropFilePath | write=host
      - OfxImageEffectPropCPURenderSupported | host_optional=true
*/
  • write: sets the default write permission (plugin or host)
  • Each property in props: can have pipe-separated modifiers:
    • | write=host — override the write permission for this property
    • | host_optional=true — mark as optional for hosts to support

@propsetdef — Reusable Property Lists

When multiple property sets share a common subset of properties, use @propsetdef to define the shared list, then reference it with _REF:

/** @propsetdef ParamsCommon
    - OfxPropType
    - OfxPropName
    - OfxPropLabel
*/

/** @propset IntParam
    write: plugin
    props:
      - ParamsCommon_REF
      - OfxParamPropDefault
*/

ParamsCommon_REF expands to all the properties listed in the ParamsCommon @propsetdef block.

@actiondef — Action Argument Definitions

An @actiondef block lists the properties passed in inArgs and outArgs for an action. Like @propdef, it goes at the end of the doxygen comment, just before */.

/** @brief Called when something in the instance is changed.

    @param handle handle to the plug-in instance
    @param inArgs has the following properties
        - \ref kOfxPropType the type of the thing that changed
        - \ref kOfxPropName the name of the thing that changed
        - \ref kOfxPropChangeReason what triggered the change

    @actiondef
    inArgs:
      - OfxPropType
      - OfxPropName
      - OfxPropChangeReason
      - OfxPropTime
      - OfxImageEffectPropRenderScale
    outArgs:
*/
#define kOfxActionInstanceChanged "OfxActionInstanceChanged"

Property names in inArgs/outArgs use the string name (without the k prefix), matching the @propdef key. Use an empty value or [] for actions with no args on that side.

Validation

Run scripts/gen-props.py to validate the metadata. It checks that:

  • Every property with a @propdef is referenced in at least one @propset or @actiondef
  • All property names referenced in @propset and @actiondef blocks have corresponding @propdef definitions
  • No duplicate property or property set names exist
⚡