Add application-help-to-doxygen (#533)

CHANGES.md

@@ -1,5 +1,7 @@
 # git master
 
+* [533](https://github.com/Eyescale/CMake/pull/533):
+  Add application-help-to-doxygen extraction
 * [532](https://github.com/Eyescale/CMake/pull/532):
   Only update SHA-1s in .gitsubprojects after ```update``` instead of rewriting
   the whole file

CommonApplication.cmake

@@ -1,12 +1,13 @@
-# Copyright (c) 2014-2016 Stefan.Eilemann@epfl.ch
+# Copyright (c) 2014-2017 Stefan.Eilemann@epfl.ch
 #                         Raphael.Dumusc@epfl.ch
 
 # Configures the build for a simple application:
-#   common_application(<Name> [GUI] [EXAMPLE])
+#   common_application(<Name> [GUI] [EXAMPLE] [NOHELP])
 #
 # Arguments:
 # * GUI: if set, build cross-platform GUI application
 # * EXAMPLE: install all sources in share/Project/examples/Name
+# * NOHELP: opt out of doxygen help extraction
 #
 # Input:
 # * NAME_SOURCES for all compilation units
@@ -19,6 +20,9 @@
 # * NAME_ICON optional .icns file (Mac OS GUI applications only)
 # * NAME_COPYRIGHT optional copyright notice (Mac OS GUI applications only)
 #
+# Output Global Properties
+# * ${PROJECT_NAME}_HELP help page names generated (see DoxygenRule.cmake)
+#
 # Builds Name application and installs it.
 
 include(AppleCheckOpenGL)
@@ -27,7 +31,7 @@ include(CMakeParseArguments)
 include(StringifyShaders)
 
 function(common_application Name)
-  set(_opts GUI EXAMPLE WIN32)
+  set(_opts GUI EXAMPLE NOHELP WIN32)
   set(_singleArgs)
   set(_multiArgs)
   cmake_parse_arguments(THIS "${_opts}" "${_singleArgs}" "${_multiArgs}"
@@ -122,6 +126,41 @@ function(common_application Name)
     endif()
   endif()
 
+  if(NOT THIS_NOHELP)
+    # run binary with --help to capture output for doxygen
+    set(_doc "${PROJECT_BINARY_DIR}/help/${Name}.md")
+    set(_cmake "${CMAKE_CURRENT_BINARY_DIR}/${Name}.cmake")
+    file(WRITE ${_cmake} "
+      execute_process(COMMAND \${APP} --help
+      OUTPUT_FILE ${_doc} ERROR_FILE ${_doc}.error)
+      file(READ ${_doc} _doc_content)
+      if(NOT _doc_content)
+        message(FATAL_ERROR \"${Name} is missing --help\")
+      endif()
+      file(WRITE ${_doc} \"${Name} {#${Name}}
+============
+
+```
+\${_doc_content}
+```
+\")
+")
+    add_custom_command(OUTPUT ${_doc}
+      COMMAND ${CMAKE_COMMAND} -DAPP=$<TARGET_FILE:${Name}> -P ${_cmake}
+      DEPENDS ${Name} COMMENT "Creating help for ${Name}")
+    add_custom_target(${Name}-help DEPENDS ${_doc})
+    set_target_properties(${Name}-help PROPERTIES
+      EXCLUDE_FROM_DEFAULT_BUILD ON FOLDER ${PROJECT_NAME}/doxygen)
+    set_property(GLOBAL APPEND PROPERTY ${PROJECT_NAME}_HELP ${Name})
+
+    if(NOT TARGET ${PROJECT_NAME}-help)
+      add_custom_target(${PROJECT_NAME}-help)
+      set_target_properties(${PROJECT_NAME}-help PROPERTIES
+        EXCLUDE_FROM_DEFAULT_BUILD ON FOLDER ${PROJECT_NAME}/doxygen)
+    endif()
+    add_dependencies(${PROJECT_NAME}-help ${Name}-help)
+  endif()
+
   if(NOT ${NAME}_OMIT_CHECK_TARGETS)
     common_check_targets(${Name})
   endif()

CommonGraph.cmake

@@ -68,7 +68,7 @@ function(common_graph Name)
     add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${Name}_tred.dot
       COMMAND ${TRED_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/${Name}.dot >
                ${CMAKE_CURRENT_BINARY_DIR}/${Name}_tred.dot
-      OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${Name}.dot)
+      DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${Name}.dot)
     add_custom_command(OUTPUT ${dest}/${Name}.png
       COMMAND ${CMAKE_COMMAND} -E make_directory ${dest}
       COMMAND ${DOT_EXECUTABLE} -o ${dest}/${Name}.png -Tpng ${CMAKE_CURRENT_BINARY_DIR}/${Name}_tred.dot

DoxygenRule.cmake

@@ -25,6 +25,10 @@
 # * ${PROJECT_NAME}_VERSION_(MINOR|MAJOR) The project's major/minor version,
 #   generally set by the project() command in the top-level CMakeLists.txt.
 #
+# Input Global Properties
+# * ${PROJECT_NAME}_HELP a list of doxygen page anchors to add to the
+#   "Application Help" page
+#
 # Optional project information
 # Output to a metadata file for html index page generation by Jekyll
 # * ${UPPER_PROJECT_NAME}_DESCRIPTION A short description of the project
@@ -88,6 +92,20 @@ if(NOT COMMON_ORGANIZATION_NAME)
   set(COMMON_ORGANIZATION_NAME Unknown)
 endif()
 
+# collect application help page
+get_property(__help GLOBAL PROPERTY ${PROJECT_NAME}_HELP)
+if(__help)
+  list(APPEND DOXYGEN_EXTRA_INPUT ${PROJECT_BINARY_DIR}/help)
+  set(__index "${PROJECT_BINARY_DIR}/help/applications.md")
+  file(WRITE ${__index} "Application Help {#apps}
+============
+
+")
+  foreach(_help ${__help})
+    file(APPEND ${__index} "* @subpage ${_help}\n")
+  endforeach()
+endif()
+
 # list-to-string transform
 string(REPLACE ";" " " DOXYGEN_EXTRA_INPUT "${DOXYGEN_EXTRA_INPUT}")
 
@@ -114,6 +132,9 @@ set_target_properties(${PROJECT_NAME}-doxygen PROPERTIES
 if(TARGET ${PROJECT_NAME}-coverage) # CoverageReport generated by "tests" in this case
   add_dependencies(${PROJECT_NAME}-doxygen ${PROJECT_NAME}-coverage)
 endif()
+if(TARGET ${PROJECT_NAME}-help)
+  add_dependencies(${PROJECT_NAME}-doxygen ${PROJECT_NAME}-help)
+endif()
 
 if(NOT TARGET doxygen)
   add_custom_target(doxygen)
@@ -200,7 +221,6 @@ set_target_properties(${PROJECT_NAME}-doxycopy PROPERTIES
 
 if(NOT TARGET doxycopy)
   add_custom_target(doxycopy)
-  set_target_properties(doxycopy PROPERTIES
-    EXCLUDE_FROM_DEFAULT_BUILD ON)
+  set_target_properties(doxycopy PROPERTIES EXCLUDE_FROM_DEFAULT_BUILD ON)
 endif()
 add_dependencies(doxycopy ${PROJECT_NAME}-doxycopy)