OpenColorIO is documentated using reStructuredText, processed by Sphinx.
The documentation primarily lives in the docs/ folder, within the main OpenColorIO repoistory.
The rST source for the C++ API documentation is extracted from comments in the public header files in export/
The Python API documentation is extracted from dummy .py files within the src/pyglue/DocStrings/ folder
Building the docs¶
Just like a regular build from source, but specify the -D OCIO_BUILD_DOCS=yes argument to CMake.
Then run the make doc target. The default HTML output will be created in build_dir/docs/build-html/
Note that CMake must be run before each invokation of make to copy the edited rST files.
$ mkdir build && cd build
Then after each change you wish to preview:
$ cmake -D OCIO_BUILD_DOCS=yes .. && make doc
Emacs rST mode¶
Emacs’ includes a mode for editing rST files. It is documented on the docutils site
One of the features it includes is readjusting the hierarchy of heading decorations (the underlines for different heading levels). To configure this to use OCIO’s convention, put the following in your .emacs.d/init.el:
(setq rst-preferred-decorations '((?= simple 0) (?* simple 0) (?+ simple 0) (?- simple 0)))