From af0f34583073918ee8d943f1314abe7b06eb74d1 Mon Sep 17 00:00:00 2001
From: Jose Luis Rivero <jrivero@osrfoundation.org>
Date: Mon, 29 Jul 2024 17:14:48 +0200
Subject: [PATCH] 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 <jrivero@osrfoundation.org>
---
 Migration.md             |  8 ++++++++
 cmake/GzCreateDocs.cmake | 28 ++++++++++++++++++----------
 2 files changed, 26 insertions(+), 10 deletions(-)

diff --git a/Migration.md b/Migration.md
index 5a2fda66..667eadd1 100644
--- 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
index 6e681b32..3d9271bc 100644
--- 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()
 
   #--------------------------------------