updated make doc for compatibility with alice-flp.docs

Author: sy-c

CMakeLists.txt

@@ -21,6 +21,11 @@ project(ReadoutCard
 # Documentation dir
 add_subdirectory(doc)
 
+# simplified build mode for doc only
+if(ONLYDOC)
+  return()
+endif()
+
 # Add compiler flags for warnings and debug symbols
 set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -pedantic -Wextra -Werror")
 

doc/CMakeLists.txt

@@ -1,27 +1,69 @@
 # @author  Barthélémy von Haller
+# @author  Sylvain Chapeland
 
-include(FindDoxygen)
+# define doc build path
+set(DOC_BUILD_DIR "${CMAKE_CURRENT_BINARY_DIR}/doc-build")
+
+# define doc installation path
+# ensures it ends with project name
+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()
 
-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)
+# log doc build/install paths
+message(STATUS "Documentation will be built in ${DOC_BUILD_DIR}")
+message(STATUS "Documentation will be installed in ${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_DOCDIR}")
 
+# general files directly from source
+install(
+  FILES
+  ${CMAKE_SOURCE_DIR}/README.md
+  TYPE DOC
+)
+install(
+  DIRECTORY ${CMAKE_SOURCE_DIR}/doc
+  TYPE DOC
+  FILES_MATCHING PATTERN "*.md" PATTERN "*.png"
+)
+
+# doxygen-generated files
+include(FindDoxygen)
 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_BUILD_DIR}"
+    WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+    COMMENT "Create the doxygen output directory"
+    VERBATIM
+  )
+
+  # install generated files
+  install(
+    DIRECTORY ${DOC_BUILD_DIR}/html
+    TYPE DOC
+    OPTIONAL # because available only after "make doc"
+  )
+else ()
+  message(WARNING "Doxygen not found")
 endif (DOXYGEN_FOUND)

doc/doxyfile.in

@@ -38,7 +38,7 @@ PROJECT_NUMBER         = @VERSION@
 # If a relative path is entered, it will be relative to the location
 # where doxygen was started. If left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = "@CMAKE_BINARY_DIR@/doc/@PROJECT_NAME@"
+OUTPUT_DIRECTORY       = "@DOC_BUILD_DIR@"
 
 # If the CREATE_SUBDIRS tag is set to YES, then doxygen will create
 # 4096 sub-directories (in 2 levels) under the output directory of each output