Deprecate BUILD_DOCS: generate always the doc target but exclude from…

… default make (#434) * Deprecate BUILD_DOCS: generate always the doc target but exclude it from ALL * Include migration notes -------- Signed-off-by: Jose Luis Rivero <[email protected]>
gazebosim · Jul 29, 2024 · af0f345 · af0f345
1 parent 916a917
commit af0f345
Show file tree

Hide file tree

Showing 2 changed files with 26 additions and 10 deletions.
diff --git a/Migration.md b/Migration.md
@@ -19,6 +19,14 @@ release will remove the deprecated code.
    The change deprecates the HIDDEN_SYMBOLS_BY_DEFAULT flag that can be
    removed.
 
+1. **Breaking**: Now the code generates always a `doc` target that can be
+   called to generate the documentation. The `doc` target is excluded from
+   the ALL target so it needs to be explicitly triggered.
+
+1. **Deprecated**: `BUILD_DOCS` CMake arguments is deprecated.
+    **Replacement**: building docs is excluded from the default build and needs
+    to be explicitly triggered by calling the `doc` target.
+
 1. **Deprecated**: `GzPython.cmake`
     **Replacement**: Use `find_package(Python3)` to find Python3 and the
               `Python3_EXECUTABLE` variable instead of `PYTHON_EXECUTABLE`.

diff --git a/cmake/GzCreateDocs.cmake b/cmake/GzCreateDocs.cmake
@@ -42,12 +42,6 @@
 #           "${GZ-<DESIGNATION>_DOXYGEN_TAGFILE} = ${GZ-<DESIGNATION>_API_URL}"
 function(gz_create_docs)
 
-  option(BUILD_DOCS "Build docs" ON)
-  if (NOT ${BUILD_DOCS})
-    message(STATUS "Building Documentation disabled via BUILD_DOCS=OFF")
-    return()
-  endif()
-
   #------------------------------------
   # Define the expected arguments
   set(options)
@@ -175,17 +169,31 @@ function(gz_create_docs)
     configure_file(${GZ_CMAKE_DOXYGEN_DIR}/api.in
                    ${CMAKE_BINARY_DIR}/api_tagfile.dox @ONLY)
 
-    add_custom_target(doc ALL
+    add_custom_target(doc
       # Generate the API tagfile
       ${DOXYGEN_EXECUTABLE} ${CMAKE_BINARY_DIR}/api_tagfile.dox
       # Generate the API documentation
       COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_BINARY_DIR}/api.dox
       WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
-
       COMMENT "Generating API documentation with Doxygen" VERBATIM)
 
-    install(FILES ${CMAKE_BINARY_DIR}/${PROJECT_NAME_LOWER}.tag.xml
-      DESTINATION ${GZ_DATA_INSTALL_DIR})
+    add_custom_command(TARGET doc
+      POST_BUILD
+      COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_BINARY_DIR}/${PROJECT_NAME_LOWER}.tag.xml ${GZ_DATA_INSTALL_DIR}
+      COMMENT "Install doxygen tag on doc target call")
+
+    if (DEFINED BUILD_DOCS)
+      message(DEPRECATION "The BUILD_DOCS option is now deprecated. For generating the"
+        "docs the 'doc' target can be called explicitly since its generated"
+        "unconditionally not including in the default build target.")
+      if (${BUILD_DOCS})
+        set_target_properties(doc PROPERTIES ALL ON)
+      endif()
+    endif()
+  else()
+    add_custom_target(doc
+    COMMAND ${CMAKE_COMMAND} -E echo "Need doxygen installation and api.in to generate documentation."
+    VERBATIM)
   endif()
 
   #--------------------------------------