Build API docs using a custom command with dependencies (#1731)

I was bumping up against the documentation not building without using a custom target, and then stumbled across this super old issue (#9), and while reading it realized I think there's a way to have the best of both world. Transitioning to using add_custom_command instead of add_custom_target avoids the "always build" issue, and adding DEPENDS arguments allows for the correct dependency tracking for the docs building, so it will only get triggered if necessary. Also for what it's worth it didn't seem that the docs take that long to build anyway. Anyway, just putting this up here for discussion, I don't know how many people are building the docs locally, but having it part of the regular cmake build without the need for an additional target seemed like a nice improvement. I also changed the find_package(Doxygen) to add the REQUIRED keyword that way the cmake configure will fail if doxygen isn't present. I think this is ok as the entire documents/CMakeLists.txt is guarded behind the MATERIALX_BUILD_DOCS option.
AcademySoftwareFoundation · Mar 11, 2024 · b9c126c · b9c126c
1 parent fc43d3e
commit b9c126c
Showing 1 changed file with 41 additions and 30 deletions.
diff --git a/documents/CMakeLists.txt b/documents/CMakeLists.txt
@@ -1,34 +1,45 @@
 set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR})
 set(DOXYGEN_HTML_OUTPUT_DIR ${DOXYGEN_OUTPUT_DIR}/html)
-set(DOXYGEN_INPUT_LIST ${CMAKE_SOURCE_DIR}/documents/DeveloperGuide/MainPage.md
-                       ${CMAKE_SOURCE_DIR}/source/MaterialXCore
-                       ${CMAKE_SOURCE_DIR}/source/MaterialXFormat
-                       ${CMAKE_SOURCE_DIR}/source/MaterialXGenShader
-                       ${CMAKE_SOURCE_DIR}/source/MaterialXGenShader/Nodes
-                       ${CMAKE_SOURCE_DIR}/source/MaterialXGenGlsl
-                       ${CMAKE_SOURCE_DIR}/source/MaterialXGenGlsl/Nodes
-                       ${CMAKE_SOURCE_DIR}/source/MaterialXGenOsl
-                       ${CMAKE_SOURCE_DIR}/source/MaterialXGenMdl
-                       ${CMAKE_SOURCE_DIR}/source/MaterialXRender
-                       ${CMAKE_SOURCE_DIR}/source/MaterialXRenderHw
-                       ${CMAKE_SOURCE_DIR}/source/MaterialXRenderGlsl
-                       ${CMAKE_SOURCE_DIR}/source/MaterialXRenderOsl
-                       )
+set(DOXYGEN_INPUT_LIST ${CMAKE_CURRENT_BINARY_DIR}/MainPage.md)
+
+set(MATERIALX_DOXYGEN_SOURCE_FOLDERS
+    ${CMAKE_SOURCE_DIR}/source/MaterialXCore
+    ${CMAKE_SOURCE_DIR}/source/MaterialXFormat
+    ${CMAKE_SOURCE_DIR}/source/MaterialXGenShader
+    ${CMAKE_SOURCE_DIR}/source/MaterialXGenShader/Nodes
+    ${CMAKE_SOURCE_DIR}/source/MaterialXGenGlsl
+    ${CMAKE_SOURCE_DIR}/source/MaterialXGenGlsl/Nodes
+    ${CMAKE_SOURCE_DIR}/source/MaterialXGenOsl
+    ${CMAKE_SOURCE_DIR}/source/MaterialXGenMdl
+    ${CMAKE_SOURCE_DIR}/source/MaterialXRender
+    ${CMAKE_SOURCE_DIR}/source/MaterialXRenderHw
+    ${CMAKE_SOURCE_DIR}/source/MaterialXRenderGlsl
+    ${CMAKE_SOURCE_DIR}/source/MaterialXRenderOsl)
+
+find_package(Doxygen REQUIRED)
+
+foreach(FOLDER ${MATERIALX_DOXYGEN_SOURCE_FOLDERS})
+    file(GLOB FOLDER_HEADERS ${FOLDER}/*.h)
+    list(APPEND DOXYGEN_INPUT_LIST ${FOLDER_HEADERS})
+endforeach()
+
 string (REPLACE ";" " " DOXYGEN_INPUT_STR "${DOXYGEN_INPUT_LIST}")
 
-find_package(Doxygen)
-
-if(DOXYGEN_FOUND)
-    configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
-    add_custom_target(MaterialXDocs ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
-                      WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
-                      COMMENT "Generating HTML documentation: ${DOXYGEN_HTML_OUTPUT_DIR}/index.html")
-    add_custom_command(TARGET MaterialXDocs PRE_BUILD
-                       COMMAND ${CMAKE_COMMAND} -E copy_directory
-                       ${CMAKE_SOURCE_DIR}/documents/DoxygenAwesome ${CMAKE_CURRENT_BINARY_DIR})
-    add_custom_command(TARGET MaterialXDocs PRE_BUILD
-                       COMMAND ${CMAKE_COMMAND} -E copy_directory
-                       ${CMAKE_SOURCE_DIR}/documents/Images ${CMAKE_CURRENT_BINARY_DIR})
-    install(DIRECTORY ${DOXYGEN_HTML_OUTPUT_DIR}
-            DESTINATION "documents" MESSAGE_NEVER)
-endif(DOXYGEN_FOUND)
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+
+add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/MainPage.md
+                   COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_SOURCE_DIR}/DeveloperGuide/MainPage.md ${CMAKE_CURRENT_BINARY_DIR}
+                   WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+                   DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/DeveloperGuide/MainPage.md)
+
+add_custom_command(OUTPUT ${DOXYGEN_HTML_OUTPUT_DIR}/index.html
+                   COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_CURRENT_SOURCE_DIR}/DoxygenAwesome ${CMAKE_CURRENT_BINARY_DIR}
+                   COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_CURRENT_SOURCE_DIR}/Images ${CMAKE_CURRENT_BINARY_DIR}
+                   COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
+                   WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+                   DEPENDS ${DOXYGEN_INPUT_LIST} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
+                   COMMENT "Generating HTML documentation: ${DOXYGEN_HTML_OUTPUT_DIR}/index.html")
+add_custom_target(MaterialXDocs ALL DEPENDS ${DOXYGEN_HTML_OUTPUT_DIR}/index.html)
+
+install(DIRECTORY ${DOXYGEN_HTML_OUTPUT_DIR}
+        DESTINATION "documents" MESSAGE_NEVER)