Build sphinx/doxygen docs with CMake

CMakeLists.txt

@@ -73,6 +73,11 @@ if (PYTHON)
   add_subdirectory(src/python)
 endif()
 
+option(DOCS "Set ON to build html documentation")
+if (DOCS)
+  add_subdirectory(docs)
+endif()
+
 # If you want to use ctest to configure, build and
 # upload the results, cmake has builtin support for
 # submitting to CDash, or any server who speaks the
@@ -107,3 +112,4 @@ endif()
 if(NOT IMATH_IS_SUBPROJECT)
   include(cmake/clang-format.cmake)
 endif()
+

INSTALL.md

@@ -81,6 +81,20 @@ can specify a local install directory to CMake via the
 
     % cmake .. -DCMAKE_INSTALL_PREFIX=$install_directory
 
+## Documentation
+
+The Imath documentation 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``. Local documentation
+generation is off by default.
+
+Building the documentation requires that sphinx, breathe, and doxygen
+are installed.
+
 ## Library Names
 
 By default the installed libraries follow a pattern for how they are
@@ -256,6 +270,9 @@ ways:
 ``IMATH_OUTPUT_SUBDIR``
   Destination sub-folder of the include path for install. Default is ``Imath``.
 
+``DOCS``
+  Build the html documentation. Default is ``OFF``.
+
 To enable half-to-float conversion using the F16C SSE instruction set
 for g++ and clang when installing Imath, add the ``-mf16c`` compiler
 option:

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,49 @@
+# 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/Imath)
+set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/docs/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(CONF_PY_IN  ${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in)
+set(CONF_PY_OUT ${CMAKE_CURRENT_BINARY_DIR}/conf.py)
+
+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)
+configure_file(${CONF_PY_IN} ${CONF_PY_OUT} @ONLY)
+
+file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})
+
+add_custom_command(OUTPUT ${DOXYGEN_INDEX_FILE}
+                   COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
+                   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.Imath=${DOXYGEN_OUTPUT_DIR}/xml
+                     -c ${CMAKE_CURRENT_BINARY_DIR}
+                   ${SPHINX_SOURCE} ${SPHINX_BUILD}
+                   WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+                   DEPENDS ${DOXYGEN_INDEX_FILE}
+                   MAIN_DEPENDENCY ${CONF_PY_OUT}
+                   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,13 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright Contributors to the OpenEXR Project.
+
 PROJECT_NAME     = "Imath"
-XML_OUTPUT       = doxyxml
 GENERATE_LATEX   = NO
 GENERATE_MAN     = NO
 GENERATE_RTF     = NO
 CASE_SENSE_NAMES = NO
-INPUT            = ../src/Imath/
+INPUT            = "@DOXYGEN_INPUT_DIR@"
+OUTPUT_DIRECTORY = "@DOXYGEN_OUTPUT_DIR@"
 RECURSIVE        = YES
 QUIET            = YES
 JAVADOC_AUTOBRIEF    = YES
@@ -13,6 +16,7 @@ GENERATE_XML         = YES
 DISTRIBUTE_GROUP_DOC = YES
 MACRO_EXPANSION      = YES
 ENABLE_PREPROCESSING = YES
+WARN_IF_UNDOCUMENTED = NO
 PREDEFINED = IMATH_CONSTEXPR14=constexpr \
              IMATH_HOSTDEVICE= \
              IMATH_INTERNAL_NAMESPACE=Imath \

docs/classes/half.rst

@@ -5,11 +5,13 @@ The half Class
 
    #include <Imath/half.h>
 
-``half`` is a 16-bit floating point number. See `The half Type`_ for
-an explanation of the representation.
+``half`` is a 16-bit floating point number. See :doc:`../float` for an
+explanation of the representation.
 
-Also, see `C-language half Conversion`_ for C-language support for
-conversion between ``half`` and ``float``.
+See :doc:`../functions/half_c` for C-language functions for conversion
+between ``half`` and ``float``. Also, see :doc:`../half_conversion`
+for information about building Imath with support for the F16C SSE
+instruction set.
 
 Example:
 

docs/conf.py → docs/conf.py.in

@@ -68,9 +68,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '3.1'
+version = '@Imath_VERSION_MAJOR@.@Imath_VERSION_MINOR@'
 # The full version, including alpha/beta/rc tags.
-release = '3.1.0'
+release = '@IMATH_VERSION@'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -138,7 +138,7 @@
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-html_logo = "images/imath-logo-blue.png"
+html_logo = "@SPHINX_SOURCE@/images/imath-logo-blue.png"
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -148,7 +148,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 = []
 
 # 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 +157,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 = {}

docs/index.rst

@@ -1,8 +1,5 @@
-.. Imath documentation master file, created by
-   sphinx-quickstart on Wed Apr 24 15:19:01 2019.
-
-Imath Technical Documentation
-=============================
+Imath |version| Technical Documentation
+=======================================
 
 Imath is a basic, light-weight, and efficient C++ representation of 2D
 and 3D vectors and matrices and other simple but useful mathematical

src/Imath/ImathBox.h

@@ -53,8 +53,8 @@ template <class V> class IMATH_EXPORT_TEMPLATE_TYPE Box
     ///	@name Constructors
 
     /// Construct an empty bounding box. This initializes the mimimum to
-    /// `std::numeric_limits<V::baseType>::max()` and the maximum to
-    /// `std::numeric_limits<V::baseType>::lowest()`.
+    /// std::numeric_limits<V::baseType>::max() and the maximum to
+    /// std::numeric_limits<V::baseType>::lowest().
     IMATH_HOSTDEVICE IMATH_CONSTEXPR14 Box() IMATH_NOEXCEPT;
 
     /// Construct a bounding box that contains a single point.
@@ -398,8 +398,8 @@ template <class T> class IMATH_EXPORT_TEMPLATE_TYPE Box<Vec2<T>>
 
     /// Set the Box to be empty. A Box is empty if the mimimum is
     /// greater than the maximum. makeEmpty() sets the mimimum to
-    /// `numeric_limits<T>::max()' and the maximum to
-    /// `numeric_limits<T>::lowest()`.
+    /// std::numeric_limits<T>::max() and the maximum to
+    /// std::numeric_limits<T>::lowest().
     IMATH_HOSTDEVICE void makeEmpty() IMATH_NOEXCEPT;
 
     /// Extend the Box to include the given point.
@@ -659,8 +659,8 @@ template <class T> class IMATH_EXPORT_TEMPLATE_TYPE Box<Vec3<T>>
 
     /// Set the Box to be empty. A Box is empty if the mimimum is
     /// greater than the maximum. makeEmpty() sets the mimimum to
-    /// `numeric_limits<T>::max()` and the maximum to
-    /// `numeric_limits<T>::lowest()`.
+    /// std::numeric_limits<T>::max() and the maximum to
+    /// std::numeric_limits<T>::lowest().
     IMATH_HOSTDEVICE void makeEmpty() IMATH_NOEXCEPT;
 
     /// Extend the Box to include the given point.

src/Imath/ImathInterval.h

@@ -104,8 +104,8 @@ template <class T> class IMATH_EXPORT_TEMPLATE_TYPE Interval
     IMATH_HOSTDEVICE IMATH_CONSTEXPR14 bool hasVolume() const IMATH_NOEXCEPT;
 
     /// Return true if the interval contains all points, false
-    /// otherwise.  An infinite box has a mimimum of `numeric_limits<T>::lowest()`
-    /// and a maximum of `numeric_limits<T>::max()`
+    /// otherwise.  An infinite box has a mimimum of std::numeric_limits<T>::lowest()
+    /// and a maximum of std::numeric_limits<T>::max()
     IMATH_HOSTDEVICE IMATH_CONSTEXPR14 bool isInfinite() const IMATH_NOEXCEPT;
 
     /// @}

src/Imath/ImathVec.h

@@ -872,6 +872,8 @@ typedef Vec4<double> V4d;
 // Normalize and length don't make sense for integer vectors, so disable them.
 //----------------------------------------------------------------------------
 
+/// @cond Doxygen_Suppress
+
 // Vec2<short>
 template <> short Vec2<short>::length() const IMATH_NOEXCEPT = delete;
 template <> const Vec2<short>& Vec2<short>::normalize() IMATH_NOEXCEPT = delete;
@@ -953,6 +955,8 @@ template <> Vec4<int64_t> Vec4<int64_t>::normalized() const IMATH_NOEXCEPT = del
 template <> Vec4<int64_t> Vec4<int64_t>::normalizedExc() const = delete;
 template <> Vec4<int64_t> Vec4<int64_t>::normalizedNonNull() const IMATH_NOEXCEPT = delete;
 
+/// @endcond Doxygen_Suppress
+
 //------------------------
 // Implementation of Vec2:
 //------------------------