Skip to content

Latest commit

 

History

History
117 lines (75 loc) · 4.12 KB

Building_the_docs.md

File metadata and controls

117 lines (75 loc) · 4.12 KB
Raw

Building the OpenImageIO documentation

The main OpenImageIO documentation can be read on OpenImageIO Documentation on ReadTheDocs.

But sometimes -- such as for developers who are editing the documentation -- it is helpful to be able to build and preview it locally. These are the steps required to build the documentation.

The main docs as they appear on ReadTheDocs consist of two parts:

  • Individual class and function documentation that are in the comments in the various public header files of OpenImageIO.
  • All the explanatory text found in src/doc/*.rst, which is processed by Sphinx to generate the final documentation, and which draw on the header documentation that was extracted by Doxygen.

Building what you need to build the docs

To be able to fully build the documentation, there are some packages you will need installed.

Python

You will need Python.

Doxygen

We don't use Doxygen for our final docs, but we do use it to generate some intermediate files used by the Sphinx documentation (via the Breathe plugin), so you'll need it installed.

You can read full build-from-source instructions for Doxygen here, but that's unnecessary for most users. There are several common ways to install via package managers:

  • Debian/Ubuntu/etc that use apt: sudo apt install doxygen
  • RHEL/CentOS/Rocky/Alma/etc/ that use yum: sudo yum install doxygen
  • Homebrew on macOS: brew install doxygen
  • MacPorts on macOS: sudo port install doxygen

Sphinx and its plugins

Our main documentation uses Sphinx, and several extensions. The easiest way to install it is via Python PIP:

  • Sphinx documentation generator: pip install -U sphinx
  • Breathe plugin for Sphinx for combining with Doxygen: pip install breathe
  • Sphinx-tabs plugin: pip install -U sphinx-tabs
  • Furo theme: pip install furo

Actually building the docs

The building of the documentation is separate from the main OpenImageIO build system.

  1. First, build OpenImageIO itself. You should probably know how to do this before you're writing documentation for other users. Note that the build itself will generate a lot of temporary files (like object files) from the compilation in the build subdirectory, and that will also be used as scratch space for building the documentation.

  2. Do the rest of these steps in src/doc:

    cd src/doc

  3. Build the Doxygen intermediate files

    # (still in the src/doc directory)
make doxygen

    Don't worry about warnings. Only worry if you see errors.

    You only need to redo this step if you do one of the following things:

    • Edit any of the .h file from which documentation is extracted. In fact, more specifically, you need to redo this step if you CHANGE any of the doxygen-based documentation in the comments of the headers.
    • Start a fresh build, change which branch you're working on, or in any way delete your build directory. Remember, as pointed out above, that this is where the documentation is built, so if it disappears, you have to start over again.

  4. Build the Sphinx documentation

    # (still in the src/doc directory)
make sphinx

    You should see output that may spew some warnings (don't worry about that) and should end with something that looks like this:

    ...
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 63 warnings.

    You need to redo this Sphinx step if you change any of the text documentation in src/doc/*.rst is changed. Note that if you are only changing the .rst files, there is no need to go all the way back to step 3 to regenerate the Doxygen files.

  5. Where are my docs?

    The HTML pages are in ../../build/sphinx

    Point your browser at index.html in that directory to view the docs.