Build sphinx/doxygen docs with CMake (#201)

* Build sphinx/doxygen docs with CMake

* The DOCS CMake option runs doxygen and sphinx to build the html
  documentation. Default if OFF. If ON, it requires doxygen and sphinx
  to be installed (found via FindSphinx.cmake).

* Describe the documentation generation option in INSTALL.md.

* Fix broken references in half.rst.

* Remove quotes around some template function names in doxygen
  comments that result in unresolved references.

Signed-off-by: Cary Phillips <[email protected]>

* Add copyright/license

Signed-off-by: Cary Phillips <[email protected]>

* Fix dependencies

Signed-off-by: Cary Phillips <[email protected]>

* Restore conf.py for RTD

Signed-off-by: Cary Phillips <[email protected]>

* Fix typo in conf.py for RTD

Signed-off-by: Cary Phillips <[email protected]>

* typo

Signed-off-by: Cary Phillips <[email protected]>

* Fix merge

Signed-off-by: Cary Phillips <[email protected]>

* Remove Doxyfile

Signed-off-by: Cary Phillips <[email protected]>

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

@@ -69,6 +69,23 @@ can specify a local install directory to CMake via the
 
     % cmake .. -DCMAKE_INSTALL_PREFIX=$install_directory
 
+
+## Documentation
+
+The Imath documentation at
+[imath.readthedocs.io](https://imath.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.
+
 ## Python Bindings
 
 To build and install the optional Python bindings for Imath, set the
@@ -253,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``.
+
 ``PYTHON``
   Build the optional Imath python bindings. Default is ``OFF``.
 

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/Imath)
+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.Imath=${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,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

@@ -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/Imath")
+  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 = { "Imath": "doxyxml/" }
+breathe_projects = { "Imath": "doxygen/xml" }
 breathe_default_project = "Imath"
 
 # 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_Imath_VERSION = "project(Imath VERSION "
+release = None
+for l in open ("../CMakeLists.txt"):
+  if l.startswith (project_Imath_VERSION):
+    release = l.split (' ')[2]
+    break
+if release == None:
+  print ("Error in conf.py: can't find Imath 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', 'Imath.tex', 'Imath 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', 'Imath Documentation',
-     ['Cary Phillips'], 1)
+     ['Contributors to the OpenEXR Project'], 1)
 ]
 
 # If true, show URL addresses after external links.
@@ -262,7 +283,8 @@
 #  dir menu entry, description, category)
 texinfo_documents = [
   ('index', 'Imath', 'Imath Documentation',
-   'Cary Phillips', 'Imath', 'One line description of project.',
+   'Contributors to the OpenEXR Project', 'Imath',
+   '2D and 3D vectors and matrices, half 16-bit floating-point type',
    'Miscellaneous'),
 ]
 

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.
@@ -401,8 +401,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.
@@ -662,8 +662,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 <> IMATH_HOSTDEVICE short Vec2<short>::length() const IMATH_NOEXCEPT = delete;
 template <> IMATH_HOSTDEVICE const Vec2<short>& Vec2<short>::normalize() IMATH_NOEXCEPT = delete;
@@ -953,6 +955,8 @@ template <> IMATH_HOSTDEVICE Vec4<int64_t> Vec4<int64_t>::normalized() const IMA
 template <> Vec4<int64_t> Vec4<int64_t>::normalizedExc() const = delete;
 template <> IMATH_HOSTDEVICE Vec4<int64_t> Vec4<int64_t>::normalizedNonNull() const IMATH_NOEXCEPT = delete;
 
+/// @endcond Doxygen_Suppress
+
 //------------------------
 // Implementation of Vec2:
 //------------------------