Move property metadata from YAML into inline @propdef blocks in headers

Also move property sets and actions from YAML into inline @propset,
@propsetdef, and @actiondef blocks in headers.

Consolidate property metadata (type, dimension, values, defaults, etc.)
from the separate ofx-props.yml file into @propdef YAML blocks within
each property's doxygen comment in the C headers. This keeps metadata
next to the code it describes, reducing maintenance burden.

- Add scripts/ofx_prop_utils.py: shared parser for @propdef blocks
- Migrate 182 properties across 10 headers with inline @propdef blocks
- Update gen-props.py and gen-props-doc.py to read from headers
- Delete properties section from ofx-props.yml (1348 -> 609 lines)
- Delete legacy doc generator (genPropertiesReference.py)
- Delete unused property_links Sphinx extension
- Simplify Documentation/build.sh and conf.py

This eliminates the YAML file entirely. All property metadata is now
co-located with the code it describes.

Generated C++ headers (ofxPropsMetadata.h, ofxPropsBySet.h, etc.) are
verified identical before and after migration, except for a few
additions noted during the migration, namely propset assignments and
action args for ThumbnailRender and CPURenderSupported.

The format for @propdef, @propsetdef and @actiondef sections is
documented in Documentation/README.md.

This commit also improves the generated doc sections and removes the
old out-of-date property reference.

Signed-off-by: Gary Oberbrunner <garyo@darkstarsystems.com>

Author: garyo

.gitignore

@@ -17,6 +17,9 @@ cmake-build.log
 build*/
 build.log
 .cache/
+__pycache__
+.claude/
+uv.lock
 
 xcuserdata
 

Documentation/README.md

@@ -9,7 +9,7 @@ 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** - Custom scripts like `genPropertiesReference.py` extract property definitions from source files
+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
@@ -43,11 +43,10 @@ cd Documentation
 
 This script performs the following steps:
 
-1. Generates property references using `genPropertiesReference.py`
-2. Generates property documentation from YAML definitions using `scripts/gen-props-doc.py`
-3. Builds Doxygen documentation from the header files
-4. Uses Breathe to collect Doxygen API docs
-5. Builds the final HTML documentation with Sphinx
+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`
@@ -162,14 +161,138 @@ The Breathe extension bridges Doxygen and Sphinx, enabling:
 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 headers
+   - For property references: They're automatically generated from inline metadata in headers (see below)
 
-3. **Property Documentation**
-   - Property definitions are extracted automatically by `genPropertiesReference.py`
-   - Format should be: `#define kOfxPropName "OfxPropName"`
-   - Add Doxygen comments above property definitions
-
-4. **Testing Changes**
+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.
+
+```c
+/** @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`.
+
+```c
+/** @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`:
+
+```c
+/** @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 `*/`.
+
+```c
+/** @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

Documentation/build.sh

@@ -17,7 +17,7 @@ catch() {
 
 # Check for prereqs
 
-if [ ! -f genPropertiesReference.py ] ; then
+if [ ! -f build.sh ] ; then
     echo "This script must be run in the Documentation directory."
     exit 1
 fi
@@ -34,14 +34,7 @@ fi
 
 rm -rf build
 
-# Generate references
-EXPECTED_ERRS="unable to resolve reference|explicit link request|found in multiple"
-$UV_RUN python genPropertiesReference.py \
-       -i ../include -o sources/Reference/ofxPropertiesReference.rst -r \
-       > /tmp/ofx-doc-build.out 2>&1
-grep -v -E "$EXPECTED_ERRS" /tmp/ofx-doc-build.out || true
-
-# Generate property documentation from YAML definitions
+# Generate property documentation from inline @propdef metadata in headers
 cd ..
 if command -v uv > /dev/null 2>&1; then
     uv run scripts/gen-props-doc.py -v >> /tmp/ofx-doc-build.out 2>&1

Documentation/genPropertiesReference.py

@@ -30,7 +30,6 @@ the API. The changes to the API are listed in an addendum.
     suites/ofxSuiteReference
     .. outdated:
     .. ofxPropertiesByObject
-    ofxPropertiesReference
     ofxPropertiesReferenceGenerated
     ofxPropertySetsGenerated
     DoxygenIndex