OCIO v2 Documentation Effort

Since the API autodoc effort is happening simultaneously it will be easier for a lot of contributors to do a light-weight build of the Sphinx docs, which doesn’t require building OCIO in its entirety.

How to Build HTML Docs

In addition to the general OCIO v2 dependencies, install Doxygen, Sphinx, and the Python packages listed in the docs/requirements.txt file.

Doxygen can be installed with a package manager, or by downloading a binary distribution from Doxygen’s website. Use one of the following commands to install Doxygen with a platform-specific package manager:

Linux (Debian, etc.):

apt-get install doxygen

Linux (Fedora, etc.):

yum install doxygen

macOS (Homebrew):

brew install doxygen

Windows (Chocolatey):

choco install doxygen.install

Sphinx and the other Python dependencies can be installed with a single pip command on all platforms:

pip install -r docs/requirements.txt

To build only the RST docs (excluding API) locally:

cd docs
mkdir _build
sphinx-build -b html . _build
<your web browser name> _build/index.html

To build all HTML docs (including API) locally:

mkdir _build
cd _build
cmake ../. -DOCIO_BUILD_DOCS=ON -DCMAKE_INSTALL_PREFIX=../_install
make -j<your thread count> docs
<your web browser name> docs/build-html/index.html

Python 3 is required to build the documentation. If you have multiple Python installs you’ll need to make sure pip and CMake find the correct version. You can manually inform cmake of which to use by adding this option to the above cmake command, which configures the documentation build:

-DPython_ROOT=<Path to Python 3 root directory>

To ease the documentation build and test on macOS one could also add these three lines in the ~/.zshrc file:

alias python=/usr/local/bin/python3
alias pip=/usr/local/bin/pip3
alias <your web browser name>=open -a "<your web browser application name>"

Quirks

The vuepress theme that we’ve migrated to has some quirks to its design. For example it only allows two nested table of contents (TOC). So things have to be organized in a slightly different way than other sphinx projects.

The root-level toc_redirect.rst points to where to find the different section TOCs. The name and contents of each sections TOC is defined in that sub-directory’s _index.rst file.

In this TOC the :caption: directive determines what the name of the section will be in the side-bar, and in the header of the website. The H1 header determines the name of the page in the right/left arrows navigation bar. In a lot of cases this ends up doubling up the name on the page, but this seems unavoidable at the present time. If additional explanatory text is put in the _index.rst files then it shouldn’t be as problematic.

The site will show all H1 headers in the side panel by default, these then expand when selected to show all H2 headers.

Due to the limited TOC and side-bar depth, we shouldn’t be afraid of looong pages with many H2 headings to break down the page into logical quadrants.