Build sphinx/doxygen docs with CMake (#1132)

* Build doxygen/sphinx docs with CMake

Signed-off-by: Cary Phillips <cary@ilm.com>

* Mention documentation in INSTALL.md

Signed-off-by: Cary Phillips <cary@ilm.com>

CMakeLists.txt

@@ -121,3 +121,8 @@ endif()
 if(NOT OPENEXR_IS_SUBPROJECT)
   include(cmake/clang-format.cmake)
 endif()
+
+option(DOCS "Set ON to build html documentation")
+if (DOCS)
+  add_subdirectory(docs)
+endif()

INSTALL.md

@@ -71,14 +71,36 @@ can specify a local install directory to cmake via the
 
     % cmake .. -DCMAKE_INSTALL_PREFIX=$install_directory
 
-## Porting Application from OpenEXR v2 to v3
+## Porting Applications from OpenEXR v2 to v3
 
 See the [porting
 guide](https://github.com/AcademySoftwareFoundation/Imath/blob/master/docs/PortingGuide2-3.md)
 for details about differences from previous releases and how to
 address them. Also refer to the porting guide for details about
 changes to Imath.
 
+## Documentation
+
+The OpenEXR technical documentation at
+[openexr.readthedocs.io](https://openexr.readthedocs.io) is generated
+via [Sphinx](https://www.sphinx-doc.org) with the
+[Breathe](https://breathe.readthedocs.io) extension using information
+extracted from header comments by [Doxgen](https://www.doxygen.nl).
+
+To build the documentation locally from the source headers and
+``.rst`` files, set the CMake option ``DOCS=ON``. This adds
+``Doxygen`` and ``Sphinx`` CMake targets. Local documentation
+generation is off by default.
+
+Building the documentation requires that sphinx, breathe, and doxygen
+are installed.
+
+Note that the [openexr.readthedocs.io](https://openexr.readthedocs.io)
+documentation takes the place of the formerly distributed .pdf
+documents in the ``docs`` folder, although readthedocs supports
+downloading of documentation in pdf format, for those who prefer it
+that way.
+
 ## Library Names
 
 By default the installed libraries follow a pattern for how they are

cmake/FindSphinx.cmake

@@ -0,0 +1,12 @@
+#Look for an executable called sphinx-build
+find_program(SPHINX_EXECUTABLE
+             NAMES sphinx-build
+             DOC "Path to sphinx-build executable")
+
+include(FindPackageHandleStandardArgs)
+
+#Handle standard arguments to find_package like REQUIRED and QUIET
+find_package_handle_standard_args(Sphinx
+                                  "Failed to find sphinx-build executable"
+                                  SPHINX_EXECUTABLE)
+

docs/CMakeLists.txt

@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright Contributors to the OpenEXR Project.
+
+set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake" ${CMAKE_MODULE_PATH})
+
+find_package(Doxygen REQUIRED)
+find_package(Sphinx REQUIRED)
+
+set(DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR}/src/lib/OpenEXRCore)
+set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/doxygen)
+set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/html/index.html)
+set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
+set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+
+set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
+set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/sphinx)
+set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html)
+
+configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
+
+file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})
+
+add_custom_command(OUTPUT ${DOXYGEN_INDEX_FILE}
+                   COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
+                   MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}
+                   COMMENT "Running doxygen"
+                   VERBATIM)
+
+add_custom_target(Doxygen ALL DEPENDS ${DOXYGEN_INDEX_FILE})
+
+add_custom_command(OUTPUT ${SPHINX_INDEX_FILE}
+                   COMMAND 
+                     ${SPHINX_EXECUTABLE} -b html
+                     # Tell Breathe where to find the Doxygen output
+                     -Dbreathe_projects.OpenEXR=${DOXYGEN_OUTPUT_DIR}/xml
+                   ${SPHINX_SOURCE} ${SPHINX_BUILD}
+                   WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+                   DEPENDS ${DOXYGEN_INDEX_FILE}
+                   MAIN_DEPENDENCY conf.py
+                   COMMENT "Generating documentation with Sphinx")
+
+add_custom_target(Sphinx ALL DEPENDS ${SPHINX_INDEX_FILE})
+
+# Add an install target to install the docs
+include(GNUInstallDirs)
+install(DIRECTORY ${SPHINX_BUILD}
+DESTINATION ${CMAKE_INSTALL_DOCDIR})

docs/Doxyfile → docs/Doxyfile.in

@@ -1,10 +1,10 @@
 PROJECT_NAME     = "OpenEXR"
-XML_OUTPUT       = doxyxml
 GENERATE_LATEX   = NO
 GENERATE_MAN     = NO
 GENERATE_RTF     = NO
 CASE_SENSE_NAMES = NO
-INPUT            = ../src/lib
+INPUT            = "@DOXYGEN_INPUT_DIR@"
+OUTPUT_DIRECTORY = "@DOXYGEN_OUTPUT_DIR@"
 RECURSIVE        = YES
 QUIET            = YES
 JAVADOC_AUTOBRIEF    = YES
@@ -38,5 +38,5 @@ PREDEFINED = \
              IMF_EXPORT_ENUM="" \
              IMF_EXPORT_TEMPLATE_TYPE="" \
              IMF_EXPORT_TEMPLATE_INSTANCE="" \
-             OPENEXR_EXPORT=""
-
+             OPENEXR_EXPORT="" \
+             EXR_EXPORT=""

docs/conf.py

@@ -23,8 +23,20 @@
 
 # hack for readthedocs to cause it to run doxygen first
 # https://github.com/rtfd/readthedocs.org/issues/388
+
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 if on_rtd:
+
+  with open("Doxyfile.in", "r") as file:
+    filedata = file.read()
+
+  doxygen_output_dir = "_build"
+  filedata = filedata.replace('@DOXYGEN_INPUT_DIR@', "../src/lib/OpenEXRCore")
+  filedata = filedata.replace('@DOXYGEN_OUTPUT_DIR@', "doxygen")
+
+  with open("Doxyfile", "w") as file:
+    file.write(filedata)
+
   from subprocess import call 
   call('doxygen')
 
@@ -44,7 +56,7 @@
 ]
 
 # Breathe extension variables
-breathe_projects = { "OpenEXR": "doxyxml/" }
+breathe_projects = { "OpenEXR": "doxygen/xml" }
 breathe_default_project = "OpenEXR"
 
 # Add any paths that contain templates here, relative to this directory.
@@ -67,10 +79,19 @@
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
+project_OpenEXR_VERSION = "project(OpenEXR VERSION "
+release = None
+for l in open ("../CMakeLists.txt"):
+  if l.startswith (project_OpenEXR_VERSION):
+    release = l.split (' ')[2]
+    break
+if release == None:
+  print ("Error in conf.py: can't find OpenEXR VERSION in ../CMakeList.txt")
+  exit(-1)
+
+v = release.split('.')
 # The short X.Y version.
-version = '3.1'
-# The full version, including alpha/beta/rc tags.
-release = '3.1.0'
+version = "%s.%s" % (v[0], v[1])
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -148,7 +169,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+#html_static_path = ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -157,11 +178,11 @@
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
+html_last_updated_fmt = '%b %d, %Y'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
-#html_use_smartypants = True
+html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
 #html_sidebars = {}
@@ -218,7 +239,7 @@
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
   ('index', 'OpenEXR.tex', 'OpenEXR Documentation',
-   'Cary Phillips', 'manual'),
+   'Contributors to the OpenEXR Project', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -248,7 +269,7 @@
 # (source start file, name, description, authors, manual section).
 man_pages = [
     ('index', 'imath', 'OpenEXR Documentation',
-     ['Cary Phillips'], 1)
+     ['Contributors to the OpenEXR Project'], 1)
 ]
 
 # If true, show URL addresses after external links.
@@ -262,7 +283,7 @@
 #  dir menu entry, description, category)
 texinfo_documents = [
   ('index', 'OpenEXR', 'OpenEXR Documentation',
-   'Cary Phillips', 'OpenEXR', 'One line description of project.',
+   'Contributors to the OpenEXR Project', 'OpenEXR', 'Professional-grade image storage format',
    'Miscellaneous'),
 ]