Fix doxygen in cmake

This has been broken for 3 years, ever since doxygen.cfg was renamed to
doxyfile. This lets us build documentation in from cmake with the 'doc'
target. One difference to the previous version (i.e. the one that was
broken before) is that this creates the documentation in the cmake
binary directory now instead of the source directory. Reasoning for this
is that cmake targets should not change files in the source directory
ideally.

Author: Hannes Steffenhagen

src/CMakeLists.txt

@@ -5,10 +5,26 @@ find_package(FLEX REQUIRED)
 
 find_package(Doxygen)
 if(DOXYGEN_FOUND)
-    add_custom_target(doc
-        "${DOXYGEN_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/doxygen.cfg"
-        WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}"
-    )
+  set(ROOT_BINARY_DIR "${CMAKE_CURRENT_BINARY_DIR}/..")
+  set(ROOT_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/..")
+  set(ORIGINAL_DOXYFILE "${CMAKE_CURRENT_SOURCE_DIR}/doxyfile")
+  set(CONFIGURED_DOXYFILE "${ROOT_BINARY_DIR}/doxyfile")
+  set(DOC_INPUT_DIRECTORY "${ROOT_SOURCE_DIR}/doc")
+  set(DOC_OUTPUT_DIRECTORY "${ROOT_BINARY_DIR}/doc")
+
+  configure_file("${CMAKE_CURRENT_SOURCE_DIR}/doxyfile.override.in" "${CONFIGURED_DOXYFILE}")
+  add_custom_target(doc
+      COMMAND "${CMAKE_COMMAND}" -E remove_directory "${DOC_OUTPUT_DIRECTORY}"
+      COMMAND "${CMAKE_COMMAND}" -E copy_directory "${DOC_INPUT_DIRECTORY}" "${DOC_OUTPUT_DIRECTORY}"
+      COMMAND "${DOXYGEN_EXECUTABLE}" "${CONFIGURED_DOXYFILE}"
+      WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}")
+
+  unset(DOC_OUTPUT_DIRECTORY)
+  unset(DOC_INPUT_DIRECTORY)
+  unset(CONFIGURED_DOXYFILE)
+  unset(ORIGINAL_DOXYFILE)
+  unset(ROOT_SOURCE_DIR)
+  unset(ROOT_BINARY_DIR)
 endif(DOXYGEN_FOUND)
 
 #   Add a bison target named 'parser'.

src/doxyfile.override.in

@@ -0,0 +1,12 @@
+# Overrides for cmake out of source builds specifically, we
+# want to avoid copying files into the main doc directory,
+# instead we should be generating the doxygen docs in our
+# cmake output directory
+
+# Note: This file is intended to be used with cmake
+# configure_file; variables like @this@ are replaced by
+# cmake variables.
+
+@INCLUDE = @ORIGINAL_DOXYFILE@
+
+OUTPUT_DIRECTORY = @DOC_OUTPUT_DIRECTORY@