Merge pull request #151 from AcademySoftwareFoundation/doc-updates2

Doc updates: Release notes for 1.5 and cleanups

Documentation/README.md

@@ -34,3 +34,34 @@ system python if you like.)
 * 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 ``
+

Documentation/build.sh

@@ -50,7 +50,7 @@ python -m breathe.apidoc -p 'ofx_reference' -m --force -g class,interface,struct
 
 
 # Build the Sphinx docs
-EXPECTED_ERRS="Explicit markup ends without|Duplicate declaration|cpp:func targets a member|undefined label"
+EXPECTED_ERRS='Explicit markup ends without|Duplicate C.*declaration|Declaration is|cpp:func targets a member|undefined label'
 sphinx-build -b html sources build > /tmp/ofx-doc-build.out 2>&1
 egrep -v "$EXPECTED_ERRS" /tmp/ofx-doc-build.out || true