Merge pull request #185 from AcademySoftwareFoundation/doc-fixes

Doc fixes: clipGetRegionOfDefinition, Interacts

Author: garyo

Documentation/README.md

@@ -2,16 +2,27 @@
 
 This is the documentation directory for OFX, the open visual effects standard.
 
-# Building Docs
+## 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** - Custom scripts like `genPropertiesReference.py` extract property definitions from source files
+
+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.
 
-Right now building the docs is somewhat manual. The below assumes
-Linux, but Mac is similar.
-
-## Prerequisites
+### 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)
@@ -21,47 +32,143 @@ Linux, but Mac is similar.
 (Virtualenv is recommended, but not required; you could install the reqs into your
 system python if you like.)
 
-## Build:
-
-* Make sure your virtualenv above is activated: `source ofx-docgen/bin/activate`
-* Generate references:
-  `python Documentation/genPropertiesReference.py -i include -o Documentation/sources/Reference/ofxPropertiesReference.rst -r`
-* Build the doxygen docs: `cd include; doxygen ofx.doxy; cd -` (you'll see
-  some warnings)
-* Build the sphinx docs:
-  `cd Documentation; sphinx-build -b html sources build`
-* Note that you can do all the above using the build script in `Documentation/build.sh`.
-* Now open
-  file:///path/to/your/ofx/openfx/Documentation/build/index.html in
-  your browser; your changes should be there.
-
-# Doxygen notes:
-
-Doxygen is used in the source and headers. The doc build process
-parses the doxygen comments to build docs, then breathe to merge them
-with the `.rst` sphinx docs. See the [Doxygen docs](https://www.doxygen.nl/manual/docblocks.html)
-
-* Params/Actions/etc. should be added to groups using `\defgroup`, `\ingroup` and `\addtogroup`. Use `@{` / `@}` to add multiple items.
-* Use `\ref` to refer to entities in doxygen.
-
-
-# RST Notes:
-
-RST (ReStructured Text) is used for the prose documentation in the `/Documentation` subtree, using Sphinx and Breathe.
-
-* Internal links:
-  - Define: `.. _target-name:` (must be *globally unique*!)
-  - Reference: ``:ref:`target-name` ``
-  - Good to put these just before section headers; the link will refer to the header in that case.
-  - See [Sphinx Docs](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref)
-  - Links to structs/etc.:
-    - ``:ref:`OfxHost<OfxHost>` ``
-  - Links to documents:
-    - ``:doc:`docname` `` (if docname starts with `/` it's absolute, otherwise rel to current file)
-  - C macros: `` :c:macro:`kOfxParamPropChoiceOrder` `` (struct/var/func/member/enum/type/... work too), 
-    see the [Doc](https://www.sphinx-doc.org/en/master/usage/domains/c.html#c-roles)
-  - You can also reference `#define`s using this syntax: ``.. doxygendefine:: kOfxImageEffectRenderUnsafe`` on its own line,
-    which pulls in the whole doxygen block for that `#define`.
-* Useful macros:
-  - `` .. literalinclude:: README.txt ``
-
+### Build Process
+
+The simplest way to build the documentation is to run the build script:
+
+```bash
+cd Documentation
+./build.sh
+```
+
+This script performs the following steps:
+
+1. Generates property references using `genPropertiesReference.py`
+2. Builds Doxygen documentation from the header files
+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
+  ```c
+  /** \defgroup PropertiesAll Property Suite */
+  /** \ingroup PropertiesAll */
+  /** \addtogroup PropertiesAll @{ ... @} */
+  ```
+
+* **Documentation Comments** - Document functions, structs, defines, etc.
+  ```c
+  /**
+   * \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
+  ```c
+  /** 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
+  ```rst
+  Section Title
+  ============
+  
+  Subsection Title
+  ---------------
+  ```
+
+* **Internal Links** - Create references between sections
+  ```rst
+  .. _target-name:
+  
+  Section Title
+  ============
+  
+  See :ref:`target-name` for more information.
+  ```
+
+* **Code Blocks** - Display code examples
+  ```rst
+  .. code-block:: c
+     
+     #define kOfxImageEffectPluginRenderThreadSafety "OfxImageEffectPluginRenderThreadSafety"
+  ```
+
+* **Including Files** - Embed external file content
+  ```rst
+  .. literalinclude:: ../examples/basic.cpp
+     :language: cpp
+     :lines: 10-20
+  ```
+
+* **Doxygen Integration** - Include Doxygen-documented items
+  ```rst
+  .. doxygendefine:: kOfxImageEffectPropSupportsMultiResolution
+  
+  .. doxygenfunction:: OfxGetPropertySet
+  
+  .. doxygenstruct:: OfxRectD
+     :members:
+  ```
+
+* **Cross-domain References** - Link to C/C++ elements
+  ```rst
+  :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 headers
+
+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**
+   - 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

Documentation/sources/Guide/ofxExample5_Circle.rst

@@ -360,11 +360,12 @@ where we set the **gHostSupportsMultiRes** global variable.
 Get Region Of Definition Action
 ===============================
 
-What is this region of definition action? Easy, an effect and a clip
-have a region of definition (RoD). This is the maximum rectangle for
-which an effect or clip can produce pixels. You can ask for RoD of a
-clip via the :cpp:func:`OfxImageEffectSuiteV1::clipGetRegionOfDefinition` function in the image
-effect suite. The RoD is currently defined in canonical coordinates [4]_.
+An effect and a clip each have a region of definition (RoD). This is
+the maximum rectangle for which an effect or clip can produce pixels.
+You can ask for the RoD of a clip via the
+:cpp:func:`OfxImageEffectSuiteV1::clipGetRegionOfDefinition` function
+in the image effect suite. The RoD is defined in canonical coordinates
+[4]_.
 
 Note that the RoD is independent of the **bounds** of a image, an
 image’s bounds may be less than, more than or equal to the RoD. It is up
@@ -378,9 +379,9 @@ drawing. Whether we do that or not is controlled by the "growRoD"
 parameter which is conditionally defined in the describe in context
 action.
 
-To set the output rod, we need to trap the
-:c:macro:`kOfxImageEffectActionGetRegionOfDefinition` action. Our MainEntry
-function now has an extra conditional in there….
+To set the plugin's output RoD, the plugin must to handle the
+:c:macro:`kOfxImageEffectActionGetRegionOfDefinition` action. The
+MainEntry function now has an extra conditional in there….
 
 `circle.cpp <https://github.com/AcademySoftwareFoundation/openfx/blob/doc/Documentation/sources/Guide/Code/Example5/circle.cpp#L978>`__