Cleanup for doc generation in the build

- Fix bug where specifying PXR_BUILD_DOCUMENTATION=ON but not having doxygen or dot would yield a build that was missing important files like <inst>/lib/usd/plugInfo.json. CMake configuration will now fail if either of these programs are missing. - Move implementation details of doc generation into Public.cmake to clean up the root CMakeLists.txt. Also remove an unnecessary private function. Fixes #1127 (Internal change: 2051989)
PixarAnimationStudios · Mar 31, 2020 · 707151f · 707151f
1 parent 7b2c501
commit 707151f
Show file tree

Hide file tree

Showing 4 changed files with 53 additions and 52 deletions.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -48,50 +48,8 @@ if (${PXR_BUILD_PRMAN_PLUGIN})
     add_subdirectory(third_party/renderman-${RENDERMAN_VERSION_MAJOR})
 endif()
 
-if (${PXR_BUILD_DOCUMENTATION})
-    # Ensure we have doxygen+graphviz available
-    find_program(DOXYGEN_EXECUTABLE
-        NAMES doxygen
-    )
-    if (NOT EXISTS ${DOXYGEN_EXECUTABLE})                                        
-        message(WARNING "Cannot run doc generation, doxygen not found.")
-        return()
-    endif()
-
-    find_program(DOT_EXECUTABLE
-        NAMES dot
-    )
-    if (NOT EXISTS ${DOT_EXECUTABLE})
-        message(WARNING "Cannot run doc generation, dot not found.")
-        return()
-    endif()
-
-    _pxrDoxyConfig_subst()
-
-    set(DOCS_DIR "${CMAKE_BINARY_DIR}")
-    set(GEN_SCRIPT "${PROJECT_SOURCE_DIR}/cmake/macros/generateDocs.py")
-    set(PXR_SOURCE_DIR "${CMAKE_SOURCE_DIR}/pxr")
-    set(THIRD_PARTY_SOURCE_DIR "${CMAKE_SOURCE_DIR}/third_party")
-
-    add_custom_target(
-        documentation
-        ALL
-        COMMAND ${PYTHON_EXECUTABLE} ${GEN_SCRIPT} ${PXR_SOURCE_DIR} ${THIRD_PARTY_SOURCE_DIR} ${CMAKE_BINARY_DIR} ${DOCS_DIR} ${DOXYGEN_EXECUTABLE} ${DOT_EXECUTABLE}
-        DEPENDS ${CMAKE_BINARY_DIR}/include/pxr/pxr.h
-    )
-
-    set(BUILT_HTML_DOCS "${DOCS_DIR}/docs/doxy_html")
-    set(INST_DOCS_ROOT  "${CMAKE_INSTALL_PREFIX}/docs")
-    install(
-        DIRECTORY ${BUILT_HTML_DOCS}
-        DESTINATION ${INST_DOCS_ROOT}
-    )
-
-    set(BUILT_XML_DOCS "${DOCS_DIR}/docs/doxy_xml")
-    install(
-        DIRECTORY ${BUILT_XML_DOCS}
-        DESTINATION ${INST_DOCS_ROOT}
-    )
+if (PXR_BUILD_DOCUMENTATION)
+    pxr_build_documentation()
 endif()   
 
 pxr_toplevel_epilogue()
diff --git a/cmake/defaults/Packages.cmake b/cmake/defaults/Packages.cmake
@@ -128,6 +128,28 @@ endif()
 
 # Developer Options Package Requirements
 # ----------------------------------------------
+if (PXR_BUILD_DOCUMENTATION)
+    find_program(DOXYGEN_EXECUTABLE
+        NAMES doxygen
+    )
+    if (EXISTS ${DOXYGEN_EXECUTABLE})                                        
+        message(STATUS "Found doxygen: ${DOXYGEN_EXECUTABLE}") 
+    else()
+        message(FATAL_ERROR 
+                "doxygen not found, required for PXR_BUILD_DOCUMENTATION")
+    endif()
+
+    find_program(DOT_EXECUTABLE
+        NAMES dot
+    )
+    if (EXISTS ${DOT_EXECUTABLE})
+        message(STATUS "Found dot: ${DOT_EXECUTABLE}") 
+    else()
+        message(FATAL_ERROR
+                "dot not found, required for PXR_BUILD_DOCUMENTATION")
+    endif()
+endif()
+
 if (PXR_VALIDATE_GENERATED_CODE)
     find_package(BISON 2.4.1 EXACT)
     # Flex 2.5.39+ is required, generated API is generated incorrectly in
@@ -136,7 +158,6 @@ if (PXR_VALIDATE_GENERATED_CODE)
     find_package(FLEX 2.5.39 EXACT)
 endif()
 
-
 # Imaging Components Package Requirements
 # ----------------------------------------------
 

diff --git a/cmake/macros/Private.cmake b/cmake/macros/Private.cmake
@@ -105,13 +105,6 @@ function(_plugInfo_subst libTarget pluginToLibraryPath plugInfoPath)
     )
 endfunction() # _plugInfo_subst
 
-# Generate a doxygen config file
-function(_pxrDoxyConfig_subst)
-    configure_file(${CMAKE_SOURCE_DIR}/pxr/usd/usd/Doxyfile.in
-                   ${CMAKE_BINARY_DIR}/Doxyfile
-    )
-endfunction()
-
 # Install compiled python files alongside the python object,
 # e.g. lib/python/pxr/Ar/__init__.pyc
 function(_install_python LIBRARY_NAME)

diff --git a/cmake/macros/Public.cmake b/cmake/macros/Public.cmake
@@ -23,6 +23,35 @@
 #
 include(Private)
 
+function(pxr_build_documentation)
+    configure_file(${CMAKE_SOURCE_DIR}/pxr/usd/usd/Doxyfile.in
+                   ${CMAKE_BINARY_DIR}/Doxyfile)
+    set(DOCS_DIR "${CMAKE_BINARY_DIR}")
+    set(GEN_SCRIPT "${PROJECT_SOURCE_DIR}/cmake/macros/generateDocs.py")
+    set(PXR_SOURCE_DIR "${CMAKE_SOURCE_DIR}/pxr")
+    set(THIRD_PARTY_SOURCE_DIR "${CMAKE_SOURCE_DIR}/third_party")
+
+    add_custom_target(
+        documentation
+        ALL
+        COMMAND ${PYTHON_EXECUTABLE} ${GEN_SCRIPT} ${PXR_SOURCE_DIR} ${THIRD_PARTY_SOURCE_DIR} ${CMAKE_BINARY_DIR} ${DOCS_DIR} ${DOXYGEN_EXECUTABLE} ${DOT_EXECUTABLE}
+        DEPENDS ${CMAKE_BINARY_DIR}/include/pxr/pxr.h
+    )
+
+    set(BUILT_HTML_DOCS "${DOCS_DIR}/docs/doxy_html")
+    set(INST_DOCS_ROOT  "${CMAKE_INSTALL_PREFIX}/docs")
+    install(
+        DIRECTORY ${BUILT_HTML_DOCS}
+        DESTINATION ${INST_DOCS_ROOT}
+    )
+
+    set(BUILT_XML_DOCS "${DOCS_DIR}/docs/doxy_xml")
+    install(
+        DIRECTORY ${BUILT_XML_DOCS}
+        DESTINATION ${INST_DOCS_ROOT}
+    )
+endfunction()
+
 function(pxr_python_bin BIN_NAME)
     set(oneValueArgs
         PYTHON_FILE