COMP: Documentation - *.Html.tar.gz file now generated

By default, documentation can either be generated running:
 make doc
or
 make doc-dev

In the dashboard script, if WITH_DOCUMENTATION is set to TRUE,
user documentation will also be generated as part of the ALL target.

A file CTK-X.Y-html.tar.gz will be generated

CMake/ctkDashboardScript.EXAMPLE.cmake

@@ -33,6 +33,7 @@ set(CTEST_CMAKE_GENERATOR "Unix Makefiles")
 set(WITH_KWSTYLE FALSE)
 set(WITH_MEMCHECK FALSE)
 set(WITH_COVERAGE TRUE)
+set(WITH_DOCUMENTATION FALSE)
 set(CTEST_BUILD_CONFIGURATION "Release")
 set(CTEST_TEST_TIMEOUT 500)
 set(CTEST_BUILD_FLAGS "-j4") # Use multiple CPU cores to build

CMakeLists.txt

@@ -176,6 +176,12 @@ ENDIF()
 OPTION(WITH_COVERAGE "Enable/Disable coverage" OFF)
 
 #-----------------------------------------------------------------------------
+# Documentation
+#
+OPTION(DOCUMENTATION_TARGET_IN_ALL "Include the custom target for building documentation in 'all'" OFF)
+MARK_AS_ADVANCED(DOCUMENTATION_TARGET_IN_ALL)
+
+#-----------------------------------------------------------------------------
 # Additional CXX/C Flags
 #
 SET(ADDITIONAL_C_FLAGS "" CACHE STRING "Additional C Flags")

Documentation/CMakeLists.txt

@@ -2,30 +2,63 @@ FIND_PACKAGE( Doxygen QUIET)
 
 IF( DOXYGEN_FOUND )
   IF( DOXYGEN_DOT_FOUND )
-  
+
+    # Automatically generate documentation at build time
+    SET(all_arg)
+    IF (DOCUMENTATION_TARGET_IN_ALL)
+      SET(all_arg "ALL")
+    ENDIF()
+
+    #
+    # User documentation
+    #
     SET( CTK_USER_DOCUMENTATION "NO" )
     SET( CTK_ADDITIONAL_EXCLUDE_PATTERN "*_p.h\  *Private.*" )
+    SET( CTK_DOCUMENTATION_HTML_TARZ TRUE)
 
     CONFIGURE_FILE( Doxyfile.txt.in
-      ${CTK_BINARY_DIR}/Documentation/UserDoxyfile.txt
-    )
+      ${CMAKE_CURRENT_BINARY_DIR}/UserDoxyfile.txt
+      )
 
-    ADD_CUSTOM_TARGET( doc 
-      ${DOXYGEN_EXECUTABLE} ${CTK_BINARY_DIR}/Documentation/UserDoxyfile.txt 
-      DEPENDS ${CTK_BINARY_DIR}/Documentation/UserDoxyfile.txt
-    ) 
+    CONFIGURE_FILE(
+      ${CMAKE_CURRENT_SOURCE_DIR}/generate_doc.cmake.in
+      ${CMAKE_CURRENT_BINARY_DIR}/generate_userdoc.cmake
+      @ONLY
+      )
 
+    SET(userdoc_output "${CMAKE_CURRENT_BINARY_DIR}/doc/html/index.html")
+    MESSAGE(userdoc_output:${userdoc_output})
+    
+    # Run doxygen as a custom command driven by a custom target.
+    ADD_CUSTOM_COMMAND(
+      OUTPUT ${userdoc_output}
+      COMMAND ${CMAKE_COMMAND} -P "${CMAKE_CURRENT_BINARY_DIR}/generate_userdoc.cmake"
+      DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/generate_userdoc.cmake"
+              "${CMAKE_CURRENT_BINARY_DIR}/UserDoxyfile.txt"
+      )
+
+    ADD_CUSTOM_TARGET(doc ${all_arg} DEPENDS ${userdoc_output})
+            
+#     ADD_CUSTOM_TARGET( doc ${all_arg}
+#       ${DOXYGEN_EXECUTABLE} ${CTK_BINARY_DIR}/Documentation/UserDoxyfile.txt 
+#       DEPENDS ${CTK_BINARY_DIR}/Documentation/UserDoxyfile.txt
+#       ) 
+
+    #
+    # Dev documentation
+    #
     SET( CTK_USER_DOCUMENTATION "YES" )
     SET( CTK_ADDITIONAL_EXCLUDE_PATTERN "" )
 
     CONFIGURE_FILE( Doxyfile.txt.in
-      ${CTK_BINARY_DIR}/Documentation/DevDoxyfile.txt
-    )
+      ${CMAKE_CURRENT_BINARY_DIR}/DevDoxyfile.txt
+      )
 
-    ADD_CUSTOM_TARGET( doc-dev 
-      ${DOXYGEN_EXECUTABLE} ${CTK_BINARY_DIR}/Documentation/DevDoxyfile.txt 
-      DEPENDS ${CTK_BINARY_DIR}/Documentation/DevDoxyfile.txt
-    ) 
+    ADD_CUSTOM_TARGET( doc-dev
+      ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/DevDoxyfile.txt
+      DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/DevDoxyfile.txt
+      )
+    
   ELSE( DOXYGEN_DOT_FOUND )
     MESSAGE( WARNING
       "Warning: Dot not found - Documentation will not be created"

Documentation/generate_doc.cmake.in

@@ -0,0 +1,64 @@
+
+# PROJECT_NAME:
+# Documentation/project name. Used in some of the resulting file names and
+# xrefs to uniquify two or more projects linked together through their 
+# Doxygen's tag files. Mandatory for each documentation set.
+# Note: might be the same as the doxyfile's PROJECT_NAME
+# Example: 
+#   PROJECT_NAME=CTK
+#
+set(PROJECT_NAME CTK)
+
+# OUTPUT_DIRECTORY:
+# Path to the Doxygen output directory (where the resulting doc is stored).
+# Note: should be the same as your doxyfile's OUTPUT_DIRECTORY
+# Example:
+#   OUTPUT_DIRECTORY @CMAKE_CURRENT_BINARY_DIR@
+#
+set(OUTPUT_DIRECTORY "@CMAKE_CURRENT_BINARY_DIR@")
+
+# CREATE_HTML_TARZ_ARCHIVE RESULTING_HTML_TARZ_ARCHIVE_FILE:
+# Create a compressed (gzip) tar archive of the html directory (located
+# under the OUTPUT_DIRECTORY), and name of the resulting archive file. 
+# Note: your doxyfile should be configured to enable HTML creation 
+#       (using GENERATE_HTML   YES)
+# Example: 
+#   CREATE_HTML_TARZ_ARCHIVE ON
+#   CREATE_HTML_TARZ_ARCHIVE @DOCUMENTATION_HTML_TARZ@
+#   RESULTING_HTML_TARZ_ARCHIVE_FILE ${OUTPUT_DIRECTORY}/CTK@CTK_MAJOR_VERSION@.@CTK_MINOR_VERSION@-html.tar.gz
+#
+set(CREATE_HTML_TARZ_ARCHIVE @CTK_DOCUMENTATION_HTML_TARZ@)
+set(RESULTING_HTML_TARZ_ARCHIVE_FILE "${OUTPUT_DIRECTORY}/${PROJECT_NAME}-@CTK_MAJOR_VERSION@.@CTK_MINOR_VERSION@-html.tar.gz")
+
+
+# ----------------------------------------------------------------------------
+# Generate documentation
+
+execute_process(
+  COMMAND "@DOXYGEN_EXECUTABLE@" "${OUTPUT_DIRECTORY}/UserDoxyfile.txt"
+  WORKING_DIRECTORY ${OUTPUT_DIRECTORY}
+  RESULT_VARIABLE rv
+  )
+
+if(rv)
+  message(FATAL_ERROR "error: Failed to generate documentation")
+endif()
+
+# ----------------------------------------------------------------------------
+# Create the *.tar.gz file
+
+#step(1 "build *.tar.gz file")
+if(CREATE_HTML_TARZ_ARCHIVE)
+  if(NOT RESULTING_HTML_TARZ_ARCHIVE_FILE STREQUAL "")
+    file(REMOVE "RESULTING_HTML_TARZ_ARCHIVE_FILE")
+    execute_process(COMMAND ${CMAKE_COMMAND} -E tar cfz ${RESULTING_HTML_TARZ_ARCHIVE_FILE} html
+      WORKING_DIRECTORY ${OUTPUT_DIRECTORY}
+      RESULT_VARIABLE rv
+      )
+    if(EXISTS "${RESULTING_HTML_TARZ_ARCHIVE_FILE}")
+      message(STATUS "info: created '${RESULTING_HTML_TARZ_ARCHIVE_FILE}'")
+    else()
+      message(STATUS "warning: could not create '${RESULTING_HTML_TARZ_ARCHIVE_FILE}'")
+    endif()
+  endif()
+endif()