Merge branch 'master' into optionalzlib

CHANGES

@@ -3,6 +3,9 @@ OpenVDB Version History
 
 Version 7.1.1 - In Development
 
+    Improvements:
+    - util::CpuTimer now uses C++11 chrono instead of TBB.
+
     Houdini:
     - Fixed a bug in the OpenVDB Points Convert SOP where the auto voxel
       transform was ignoring the contents of packed geometry.
@@ -19,6 +22,8 @@ Version 7.1.1 - In Development
     - Upgraded CMake minimum version support to 3.12.
     - Removed OPENVDB_STATIC_SPECIALIZATION macro which is no longer required.
     - Fixed various compiler warnings for GCC 9.1.
+    - Moved to CMake doxygen commands and removed the doxygen-config files for
+      doxygen documentation.
     - Added USE_ZLIB compiler flag that enables zlib compression and defaults
       to on.
 

doc/CMakeLists.txt

@@ -8,11 +8,7 @@
 #]=======================================================================]
 
 cmake_minimum_required(VERSION 3.12)
-
-# Monitoring <PackageName>_ROOT variables
-if(POLICY CMP0074)
-  cmake_policy(SET CMP0074 NEW)
-endif()
+project(OpenVDBDocs LANGUAGES NONE)
 
 # If OPENVDB_DOXYGEN_HOUDINI is set, the Houdini documentation is also
 # built. You can provide this module a value for Houdini_VERSION which will
@@ -23,23 +19,102 @@ endif()
 # all documentation is included.
 option(OPENVDB_DOXYGEN_HOUDINI "Build Houdini documentation" ON)
 
-# Add the doxygen command if required - do this here so we guarantee
-# not to error on unrelated build issues
-find_package(Doxygen REQUIRED)
-if(DOXYGEN_VERSION VERSION_LESS MINIMUM_DOXYGEN_VERSION)
-  message(WARNING "The doxygen-config doxyfile has been generated with version "
-    "\"${MINIMUM_DOXYGEN_VERSION}\". Found Doxygen version \"${DOXYGEN_VERSION}\". "
-    "Documentation may contain errors."
-  )
+
+find_package(Doxygen REQUIRED doxygen)
+if(MINIMUM_DOXYGEN_VERSION)
+  if(DOXYGEN_VERSION VERSION_LESS MINIMUM_DOXYGEN_VERSION)
+    message(WARNING "The doxygen-config doxyfile has been generated with version "
+      "\"${MINIMUM_DOXYGEN_VERSION}\". Found Doxygen version \"${DOXYGEN_VERSION}\". "
+      "Documentation may contain errors."
+    )
+  endif()
 endif()
 
-# @todo use cmake doxygen functions available from cmake 3.9
-file(READ ${CMAKE_CURRENT_SOURCE_DIR}/doxygen-config DOXYGEN_CONFIG_CONTENT)
-file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/openvdb/cmake-doxygen-config ${DOXYGEN_CONFIG_CONTENT})
+set(DOXY_FILES
+  openvdb/openvdb
+  openvdb/openvdb/io
+  openvdb/openvdb/math
+  openvdb/openvdb/points
+  openvdb/openvdb/python/pyopenvdb.h
+  openvdb/openvdb/tools
+  openvdb/openvdb/tree
+  openvdb/openvdb/util
+  doc/build.txt
+  doc/changes.txt
+  doc/codingstyle.txt
+  doc/dependencies.txt
+  doc/doc.txt
+  doc/examplecode.txt
+  doc/faq.txt
+  doc/math.txt
+  doc/points.txt
+  doc/python.txt)
+
+set(DOXYGEN_PROJECT_NAME "OpenVDB")
+set(DOXYGEN_PROJECT_NUMBER "7.1.1")
+set(DOXYGEN_PROJECT_BRIEF "")
+set(DOXYGEN_FILE_PATTERNS "*.h") # headers only
+set(DOXYGEN_IMAGE_PATH "doc/img")
+set(DOXYGEN_RECURSIVE NO)
+
+set(DOXYGEN_GENERATE_HTML YES)
+set(DOXYGEN_GENERATE_MAN NO)
+set(DOXYGEN_GENERATE_LATEX NO)
+
+set(DOXYGEN_HTML_COLORSTYLE_HUE 4)
+set(DOXYGEN_HTML_COLORSTYLE_SAT 222)
+set(DOXYGEN_HTML_TIMESTAMP NO) # for simpler website diffs
+
+set(DOXYGEN_EXTRACT_ALL YES)
+set(DOXYGEN_EXTRACT_STATIC YES)
+set(DOXYGEN_EXTRACT_LOCAL_CLASSES NO)
+
+set(DOXYGEN_ALPHABETICAL_INDEX NO)
+set(DOXYGEN_DISTRIBUTE_GROUP_DOC YES)
+set(DOXYGEN_FULL_PATH_NAMES NO)
+set(DOXYGEN_GENERATE_TODOLIST NO)
+set(DOXYGEN_HIDE_IN_BODY_DOCS YES)
+set(DOXYGEN_HIDE_SCOPE_NAMES YES)
+set(DOXYGEN_INLINE_INHERITED_MEMB YES)
+set(DOXYGEN_MACRO_EXPANSION YES)
+set(DOXYGEN_CLASS_DIAGRAMS NO) # @todo use dot with class diagrams for relevant classes
+
+set(DOXYGEN_QUIET YES)
+
+set(DOXYGEN_ALIASES
+  [[ijk="(<i>i</i>,&nbsp;<i>j</i>,&nbsp;<i>k</i>)"]]
+  [[xyz="(<i>x</i>,&nbsp;<i>y</i>,&nbsp;<i>z</i>)"]]
+  [[const="<tt>const</tt>"]]
+  [["vdbnamespace=openvdb::v7_1"]]
+  [["hunamespace=houdini_utils"]]
+  [["hvdbnamespace=openvdb_houdini"]]
+  # Use this command to create a link to an OpenVDB class, function, etc.
+  # Usage is "@vdblink{<symbol>,<text>}", where <symbol> is a fully namespace-
+  # qualified symbol minus the openvdb and version number namespace components
+  # and <text> is the text of the link.
+  # Example: @vdblink{tree::RootNode,root node}
+  [[vdblink{2}="@link @vdbnamespace::\1 \2@endlink"]]
+  # Deprecated; use the two-argument overload defined above.
+  [[vdblink="@link @vdbnamespace"]]
+  # Use these commands to create links to OpenVDB Houdini symbols.
+  # Usage is "@hulink{<symbol>,<text>}", where <symbol> is the name of
+  # a symbol in the houdini_utils namespace and <text> is the text of the link
+  # (and likewise for @hvdblink).
+  # Example: @hulink{ParmFactory::setDefault(),setDefault}
+  # These stub implementations are used when Houdini support is disabled;
+  # see doxygen-config-houdini for the full implementations.
+  [[hulink{2}="<B>\2</B>"]]
+  [[hvdblink{2}="<B>\2</B>"]]
+  )
+
+set(DOXYGEN_PREDEFINED
+  "OPENVDB_VERSION_NAME=v7_1"
+  "OPENVDB_ABI_VERSION_NUMBER=7"
+  [[__declspec(x):= __attribute__(x):=]]
+  "OPENVDB_USE_LOG4CPLUS=")
+
 if(OPENVDB_DOXYGEN_HOUDINI)
   # Append Houdini-specific settings to the Doxygen config file.
-  file(READ ${CMAKE_CURRENT_SOURCE_DIR}/doxygen-config-houdini DOXYGEN_CONFIG_CONTENT)
-  file(APPEND ${CMAKE_CURRENT_BINARY_DIR}/openvdb/cmake-doxygen-config ${DOXYGEN_CONFIG_CONTENT})
   if(Houdini_VERSION)
     # Extract the components of the Houdini version number into a list.
     string(REPLACE "." ";" HOUDINI_VERSION_COMPONENTS ${Houdini_VERSION})
@@ -55,23 +130,46 @@ if(OPENVDB_DOXYGEN_HOUDINI)
   # Append Houdini version number macros to the Doxygen config file so that
   # the generated documentation reflects the API for that version
   # (i.e, taking into account any conditionally compiled blocks).
-  set(DOXYGEN_CONFIG_CONTENT
-    "PREDEFINED += UT_MAJOR_VERSION_INT=${HVERS_MAJOR}\n"
-    "PREDEFINED += UT_MINOR_VERSION_INT=${HVERS_MINOR}\n"
-    "PREDEFINED += UT_VERSION_INT=${HVERS_INT}\n\n")
-  file(APPEND ${CMAKE_CURRENT_BINARY_DIR}/openvdb/cmake-doxygen-config
-      ${DOXYGEN_CONFIG_CONTENT})
+  list(APPEND DOXYGEN_PREDEFINED "UT_MAJOR_VERSION_INT=${HVERS_MAJOR}")
+  list(APPEND DOXYGEN_PREDEFINED "UT_MINOR_VERSION_INT=${HVERS_MINOR}")
+  list(APPEND DOXYGEN_PREDEFINED "UT_VERSION_INT=${HVERS_INT}")
+
+  list(APPEND DOXYGEN_ALIASES
+    [[hulink{2}="@link @hunamespace::\1 \2@endlink"]]
+    [[hvdblink{2}="@link @hvdbnamespace::\1 \2@endlink"]]
+    # Deprecated; use the two-argument overloads defined above.
+    [[hulink="@link @hunamespace"]]
+    [[hvdblink="@link @hvdbnamespace"]]
+    )
+
+  set(DOXYGEN_ENABLED_SECTIONS "OPENVDB_HOUDINI")
+
+  list(APPEND DOXY_FILES
+    doc/houdini.txt
+    openvdb_houdini/openvdb_houdini/AttributeTransferUtil.h
+    openvdb_houdini/openvdb_houdini/GEO_PrimVDB.h
+    openvdb_houdini/openvdb_houdini/GT_GEOPrimCollectVDB.h
+    openvdb_houdini/openvdb_houdini/GU_PrimVDB.h
+    openvdb_houdini/openvdb_houdini/GU_VDBPointTools.h
+    openvdb_houdini/openvdb_houdini/GeometryUtil.h
+    openvdb_houdini/openvdb_houdini/OP_NodeChain.h
+    openvdb_houdini/openvdb_houdini/ParmFactory.h
+    openvdb_houdini/openvdb_houdini/PointUtils.h
+    openvdb_houdini/openvdb_houdini/SOP_NodeVDB.h
+    openvdb_houdini/openvdb_houdini/SOP_VDBVerbUtils.h
+    openvdb_houdini/openvdb_houdini/UT_VDBTools.h
+    openvdb_houdini/openvdb_houdini/UT_VDBUtils.h
+    openvdb_houdini/openvdb_houdini/Utils.h)
 endif()
-file(APPEND ${CMAKE_CURRENT_BINARY_DIR}/openvdb/cmake-doxygen-config
-  "QUIET=YES\nOUTPUT_DIRECTORY=${CMAKE_CURRENT_BINARY_DIR}/openvdb/doc\n"
-)
 
-add_custom_target(doc ALL
-  COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/openvdb/cmake-doxygen-config
-  WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
-  COMMENT "Generating API documentation with Doxygen" VERBATIM
-)
+set(DOXYGEN_VERBATIM_VARS DOXYGEN_ALIASES DOXYGEN_PREDEFINED)
+
+# Always add to build target (can't use USE_STAMP_FILE as we include
+# complete directories in DOXY_FILES)
+doxygen_add_docs(doc ${DOXY_FILES}
+  ALL WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+  COMMENT "Generating API documentation with Doxygen")
 
 # Suppress "Installing..." messages for all but one of the hundreds of generated files.
-install(FILES ${CMAKE_CURRENT_BINARY_DIR}/openvdb/doc/html/index.html DESTINATION doc/html)
-install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/openvdb/doc/html DESTINATION doc MESSAGE_NEVER)
+install(FILES ${CMAKE_CURRENT_BINARY_DIR}/html/index.html DESTINATION doc/html)
+install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html DESTINATION doc MESSAGE_NEVER)

doc/changes.txt

@@ -6,6 +6,10 @@
 @par
 <B>Version 7.1.1</B> - <I>In Development</I>
 
+@par
+Improvements:
+- util::CpuTimer now uses C++11 chrono instead of TBB.
+
 @par
 Houdini:
 - Fixed a bug in the OpenVDB Points Convert SOP where the auto voxel
@@ -24,9 +28,12 @@ Build:
 - Upgraded CMake minimum version support to 3.12.
 - Removed OPENVDB_STATIC_SPECIALIZATION macro which is no longer required.
 - Fixed various compiler warnings for GCC 9.1.
+- Moved to CMake doxygen commands and removed the doxygen-config files for
+  doxygen documentation.
 - Added USE_ZLIB compiler flag that enables zlib compression and defaults
   to on.
 
+
 @htmlonly <a name="v7_1_0_changes"></a>@endhtmlonly
 @par
 <B>Version 7.1.0</B> - <I>August 13, 2020</I>