Generate Doxygen documentation with 'make doc' only in out-of-source build

directory -- don't clutter source directory.  (I'm proud of this)

CMake/GenerateDoxyfile.cmake

@@ -0,0 +1,35 @@
+cmake_minimum_required(VERSION 2.8)
+
+# We need to modify the Doxyfile slightly.  We'll copy the Doxyfile into the
+# build directory, update the location of the source, and then run Doxygen and
+# it will generate the documentation into the build directory.
+
+message(STATUS "Hurble ${CMAKE_CURRENT_SOURCE_DIR}")
+
+# First, read the Doxyfile in as a variable.
+file(READ "${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile" DOXYFILE_CONTENTS)
+
+# Now, modify all the "INPUT" paths.  I've written each of the three out by
+# hand.  If more are added, they'll need to be added here too.
+string(REPLACE
+    "./src/mlpack"
+    "${CMAKE_CURRENT_SOURCE_DIR}/src/mlpack"
+    DOXYFILE_AUXVAR "${DOXYFILE_CONTENTS}"
+)
+
+string(REPLACE
+    "./doc/guide"
+    "${CMAKE_CURRENT_SOURCE_DIR}/doc/guide"
+    DOXYFILE_CONTENTS "${DOXYFILE_AUXVAR}"
+)
+
+string(REPLACE
+    "./doc/tutorials"
+    "${CMAKE_CURRENT_SOURCE_DIR}/doc/tutorials"
+    DOXYFILE_AUXVAR "${DOXYFILE_CONTENTS}"
+)
+
+message(STATUS "Ready to go ${DESTDIR}")
+
+# Save the Doxyfile to its new location.
+file(WRITE "${DESTDIR}/Doxyfile" "${DOXYFILE_AUXVAR}")

CMakeLists.txt

@@ -143,18 +143,21 @@ add_subdirectory(src/mlpack)
 # I guess this option will just be unavailable.
 find_package(Doxygen)
 if (DOXYGEN_FOUND)
-  # It may be better if we built the documentation into the build directory, but
-  # I'm leaving this for a later day.
-  add_custom_target(doc
-      ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile
+  # Preprocess the Doxyfile.  This is done before 'make doc'.
+  add_custom_command(OUTPUT ${CMAKE_BINARY_DIR}/Doxyfile
+      PRE_BUILD
+      COMMAND ${CMAKE_COMMAND} -D DESTDIR=${CMAKE_BINARY_DIR} -P
+          ${CMAKE_CURRENT_SOURCE_DIR}/CMake/GenerateDoxyfile.cmake
       WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
-      COMMENT "Generating API documentation with Doxygen"
+      COMMENT "Creating Doxyfile to generate Doxygen documentation"
   )
-  add_custom_command(TARGET doc
-      POST_BUILD
-      COMMAND cmake -E copy_directory
-          ${CMAKE_CURRENT_SOURCE_DIR}/doc ${CMAKE_BINARY_DIR}/doc
-      COMMENT "Copying API documentation to build directory"
+
+  # Generate documentation.
+  add_custom_target(doc
+      COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_BINARY_DIR}/Doxyfile
+      DEPENDS ${CMAKE_BINARY_DIR}/Doxyfile
+      WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+      COMMENT "Generating API documentation with Doxygen"
   )
 
   install(DIRECTORY ${CMAKE_BINARY_DIR}/doc/html