build: add documentation

.github/workflows/ccpp.yml

@@ -18,3 +18,11 @@ jobs:
     - uses: actions/checkout@v2
     - name: build debian package
       run: rm -rf build || true && mkdir build && cd build && cmake .. -DLIBMBUS_PACKAGE_DEB=ON && cpack .. && sudo dpkg -i *.deb && ls /usr/lib
+
+  doc:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: build doxygen documentation
+      run: rm -rf build || true && mkdir build && cd build && cmake .. -DLIBMBUS_BUILD_DOCS=ON && cmake --build . --target doc
+

CMakeLists.txt

@@ -1,6 +1,9 @@
 cmake_minimum_required(VERSION 3.5)
 
-project(libmbus LANGUAGES CXX C VERSION "0.9.0")
+project(
+  libmbus
+  LANGUAGES CXX C
+  VERSION "0.9.0")
 
 if(CMAKE_BUILD_TYPE STREQUAL "")
   message(STATUS "CMAKE_BUILD_TYPE empty setting to Debug")
@@ -18,6 +21,7 @@ option(LIBMBUS_ENABLE_COVERAGE "build with coverage support" ON)
 option(LIBMBUS_RUN_CLANG_TIDY "use Clang-Tidy for static analysis" OFF)
 option(LIBMBUS_PACKAGE_DEB "build debian package" OFF)
 option(LIBMBUS_PACKAGE_RPM "build rpm package" OFF)
+option(LIBMBUS_BUILD_DOCS "build documentation" OFF)
 
 set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
@@ -200,7 +204,8 @@ set(CPACK_COMPONENTS_ALL devel libs)
 set(CPACK_RESOURCE_FILE_LICENSE ${PROJECT_SOURCE_DIR}/LICENSE)
 
 set(CPACK_PACKAGE_VERSION "${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}.${PROJECT_VERSION_PATCH}")
-set(CPACK_PACKAGE_FILE_NAME "${CMAKE_PROJECT_NAME}_${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}.${CPACK_PACKAGE_VERSION_PATCH}")
+set(CPACK_PACKAGE_FILE_NAME
+    "${CMAKE_PROJECT_NAME}_${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}.${CPACK_PACKAGE_VERSION_PATCH}")
 set(CPACK_COMPONENTS_ALL Libraries ApplicationData)
 
 if(LIBMBUS_PACKAGE_DEB)
@@ -219,3 +224,37 @@ if(LIBMBUS_PACKAGE_RPM)
 endif()
 
 include(CPack)
+
+# ##############################################################################
+# doc
+# mkdir build ; cd build ; cmake .. -DLIBMBUS_BUILD_DOCS=ON ; cmake --build . --target doc
+# ##############################################################################
+
+if(LIBMBUS_BUILD_DOCS)
+  message(STATUS "building with documentation")
+  # Generate targets for documentation
+  # check if Doxygen is installed
+  find_package(Doxygen)
+
+  if(Doxygen_FOUND)
+    # set input and output files
+    set(DOXYGEN_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
+    set(DOXYGEN_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+
+    # request to configure the file
+    configure_file(${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY)
+
+    # note the option ALL which allows to build the docs together with the application
+    add_custom_target(
+      doc ALL
+      COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_OUT}
+      WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+      COMMENT "Generating API documentation with Doxygen"
+      VERBATIM)
+
+    message(STATUS "Setup up the Doxygen documention build")
+
+  else(Doxygen_FOUND)
+    message(WARNING "Doxygen need to be installed to generate the doxygen documentation")
+  endif(Doxygen_FOUND)
+endif()

Doxyfile.in

@@ -25,13 +25,13 @@ DOXYFILE_ENCODING      = UTF-8
 # The PROJECT_NAME tag is a single word (or a sequence of words surrounded
 # by quotes) that should identify the project.
 
-PROJECT_NAME           = libmbus
+PROJECT_NAME           = "@CMAKE_PROJECT_NAME@"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number.
 # This could be handy for archiving the generated documentation or
 # if some version control system is used.
 
-PROJECT_NUMBER         =
+PROJECT_NUMBER         = @VERSION_MAJOR@.@VERSION_MINOR@.@VERSION_PATCH@
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
 # base path where the generated documentation will be put.
@@ -581,7 +581,7 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories
 # with spaces.
 
-INPUT                  = mbus 
+INPUT                  = @CMAKE_CURRENT_LIST_DIR@/mbus 
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
@@ -1628,3 +1628,6 @@ GENERATE_LEGEND        = YES
 # the various graphs.
 
 DOT_CLEANUP            = YES
+
+
+USE_MDFILE_AS_MAINPAGE = @CMAKE_CURRENT_LIST_DIR@/README.md

build.sh

@@ -15,3 +15,10 @@ cmake --build .
 # cmake .. -DLIBMBUS_PACKAGE_DEB=ON
 # cpack ..
 # dpkg -i *.deb
+
+# build doc
+
+# mkdir build
+# cd build
+# cmake .. -DLIBMBUS_BUILD_DOCS=ON
+# cmake --build . --target doc