Enhancement: Add a target to build the docs in the binary output directory

Added a Doxygen "doc" target in source/CMakeLists.txt which will build the
Doxygen documentation in the build directory. To achieve this the
source/opener.doxyfile was renamed to opener.doxyfile.in and will be
configured by the CMake run.

This change was done to achieve three goals:
- The documentation is moved out of the source directory.
- The documentation excludes now the source files not belonging to the port
  that is currently built. Documentation for the three platforms can be
  different.
- The OpENer major and minor revision is automatically configured in the
  generated opener.doxyfile.

Signed-off-by: Stefan Mätje <stefan.maetje@esd.eu>

source/CMakeLists.txt

@@ -83,6 +83,44 @@ endif(OpENer_TRACES)
 #######################################
 set( OPENER_BUILD_SHARED_LIBS OFF CACHE BOOL "Builds OpENer as separate lib and sample application" )
 
+#######################################
+# OpENer documentation target "doc"   #
+#######################################
+
+# check if Doxygen is installed
+find_package(Doxygen)
+if (DOXYGEN_FOUND)
+    # set input and output files
+    set(DOXYGEN_IN ${OpENer_SOURCE_DIR}/opener.doxyfile.in)
+    set(DOXYGEN_OUT ${OpENer_BINARY_DIR}/opener.doxyfile)
+
+    # exclude subdirectories of non active platforms depending on OpENer_PLATFORM
+    set(OpENer_EXCLUDE_PATTERNS "")
+    if (NOT (${OpENer_PLATFORM} STREQUAL "POSIX"))
+        set(OpENer_EXCLUDE_PATTERNS "${OpENer_EXCLUDE_PATTERNS} */src/ports/POSIX/*")
+    endif ()
+    if (NOT (${OpENer_PLATFORM} STREQUAL "WIN32"))
+        set(OpENer_EXCLUDE_PATTERNS "${OpENer_EXCLUDE_PATTERNS} */src/ports/WIN32/*")
+    endif ()
+    if (NOT (${OpENer_PLATFORM} STREQUAL "MINGW"))
+        set(OpENer_EXCLUDE_PATTERNS "${OpENer_EXCLUDE_PATTERNS} */src/ports/MINGW/*")
+    endif ()
+
+    # request to configure the file
+    configure_file(${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY)
+
+    # note the option ALL which will build the docs always with the default target
+    add_custom_target( doc # ALL
+        COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_OUT}
+        WORKING_DIRECTORY ${OpENer_BINARY_DIR}
+        COMMENT "Generating API documentation with Doxygen"
+        VERBATIM )
+    message("-- Doxygen setup done")
+else (DOXYGEN_FOUND)
+  message("Doxygen needs to be installed to generate the Doxygen documentation")
+endif (DOXYGEN_FOUND)
+
+
 #######################################
 # Test switch                         #
 #######################################

source/opener.doxyfile → source/opener.doxyfile.in

@@ -38,7 +38,7 @@ PROJECT_NAME           = "OpENer - Open Source EtherNet/IP(TM)  I/O Target Stack
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 2.2
+PROJECT_NUMBER         = @OpENer_VERSION_MAJOR@.@OpENer_VERSION_MINOR@
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
@@ -58,7 +58,7 @@ PROJECT_LOGO           =
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = doc/api_doc
+OUTPUT_DIRECTORY       = @OpENer_BINARY_DIR@/api_doc
 
 # 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 format and
@@ -758,7 +758,7 @@ WARN_LOGFILE           =
 # spaces.
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = src
+INPUT                  = @OpENer_SOURCE_DIR@/src
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -793,9 +793,7 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = src/ports/platform-pc/.deps \
-                         src/enet_encap/.deps \
-                         src/cip/.deps
+EXCLUDE                =
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -811,7 +809,7 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       = 
+EXCLUDE_PATTERNS       = */.deps @OpENer_EXCLUDE_PATTERNS@
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
@@ -828,7 +826,7 @@ EXCLUDE_SYMBOLS        =
 # that contain example code fragments that are included (see the \include
 # command).
 
-EXAMPLE_PATH           = ./
+EXAMPLE_PATH           = @OpENer_SOURCE_DIR@
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and