cmake doc cleanup

Author: sy-c

CMakeLists.txt

@@ -13,6 +13,16 @@ project(
   LANGUAGES CXX C
 )
 
+# default install dirs	
+include(GNUInstallDirs)
+
+# add subdirectories
+add_subdirectory(doc)
+# stop immediately for easy building of doc only
+if(ONLYDOC)
+  return()
+endif()
+
 # global compilation options
 set(CMAKE_CXX_STANDARD 14)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
@@ -23,15 +33,11 @@ set(CMAKE_POSITION_INDEPENDENT_CODE ON)
 # build-time binaries
 set(EXECUTABLE_OUTPUT_PATH "${CMAKE_BINARY_DIR}/bin")
 # installation
-include(GNUInstallDirs)
 set(CMAKE_INSTALL_LIBDIR lib)
 
 # add local modules directory
 list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/cmake")
 
-# add subdirectories
-add_subdirectory(doc)
-
 # dependencies to build the InfoLogger components
 # NB: cmake/InfoLoggerConfig.cmake defines dependencies for clients using the library
 #find_package(Common REQUIRED)

doc/CMakeLists.txt

@@ -1,27 +1,60 @@
-# @author  Barthélémy von Haller
-
 include(FindDoxygen)
 
-if(NOT DOXYGEN_DOT_FOUND)
-  message(WARNING "Graphviz doesn't seem to be installed. Doxygen will not be able to generate graphs. Consider installing this package.")
-endif(NOT DOXYGEN_DOT_FOUND)
+# put doc in a subdirectory with project name, if not already set so
+if (NOT CMAKE_INSTALL_DOCDIR)
+  set(CMAKE_INSTALL_DOCDIR "doc")
+endif()
+if (NOT "${CMAKE_INSTALL_DOCDIR}" MATCHES "${PROJECT_NAME}$")
+  set(CMAKE_INSTALL_DOCDIR "${CMAKE_INSTALL_DOCDIR}/${PROJECT_NAME}")
+endif()
+set(DOC_OUTPUT_DIR "${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_INSTALL_DOCDIR}")
+
+# log doc build(install paths)
+message(STATUS "Documentation will be generated in ${DOC_OUTPUT_DIR}")
+message(STATUS "Documentation will be installed in ${CMAKE_INSTALL_DOCDIR}")
 
+# general files directly from source
+install(
+  DIRECTORY . 
+  TYPE DOC
+  FILES_MATCHING PATTERN "*.md" PATTERN "*.png"
+)
+
+# doxygen-generated files
 if (DOXYGEN_FOUND)
-  # Configure the doxygen config file with current settings
-  set("DOC_OUTPUT_DIR" "${CMAKE_CURRENT_BINARY_DIR}")
+  if(NOT DOXYGEN_DOT_FOUND)
+    message(WARNING "dot not found. Please install Graphviz.")
+  endif(NOT DOXYGEN_DOT_FOUND)
+
+  # configure the doxygen config file with current cmake settings
   configure_file(doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/documentation-config.doxygen @ONLY)
 
-  # target doc
-  add_custom_target(doc
-          ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/documentation-config.doxygen
-          WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
-          COMMENT "Generating API documentation using doxygen for ${PROJECT_NAME}
-                     \n  Output will be available in ${DOC_OUTPUT_DIR}/html" VERBATIM)
-
-  # installation
-  option(DOC_INSTALL "Install the documentation when calling \"make install\"" OFF)
-  if(DOC_INSTALL)
-    message(STATUS "Documentation will be installed but you *must* run `make doc`")
-    install(DIRECTORY ${DOC_OUTPUT_DIR}/html DESTINATION share/doc/${PROJECT_NAME} COMPONENT doc)
-  endif(DOC_INSTALL)
+  # build documentation with target "doc"
+  add_custom_target(
+    doc
+    ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/documentation-config.doxygen
+    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+    COMMENT "Generating API documentation using doxygen for ${PROJECT_NAME}"
+    VERBATIM
+    DEPENDS doc-dir
+  )
+
+  # doxygen fails creating multi-level output directory, make sure it exists
+  add_custom_target(
+    doc-dir
+    COMMAND ${CMAKE_COMMAND} -E make_directory "${DOC_OUTPUT_DIR}"
+    WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+    COMMENT "Create the doxygen output directory"
+    VERBATIM
+  )
+
+  # install generated files
+  install(
+    DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_INSTALL_DOCDIR}/html
+    TYPE DOC
+    OPTIONAL # because available only after "make doc"
+  )
+else (DO)
+  message(WARNING "Doxygen not found")
 endif (DOXYGEN_FOUND)
+

doc/doxyfile.in

@@ -734,7 +734,6 @@ WARN_LOGFILE           =
 # Note: If this tag is empty the current directory is searched.
 
 INPUT                  = "@PROJECT_SOURCE_DIR@/include" \
-                         "@PROJECT_BINARY_DIR@/include" \
                          "@PROJECT_SOURCE_DIR@/src" \
                          "@PROJECT_SOURCE_DIR@/doc"
 
@@ -2055,7 +2054,7 @@ DOT_NUM_THREADS        = 0
 # The default value is: Helvetica.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOT_FONTNAME           = FreeSans
+#DOT_FONTNAME           = FreeSans
 
 # The DOT_FONTSIZE tag can be used to set the size (in points) of the font of
 # dot graphs.