Merge pull request #32 from DeveloperPaul123/feature/documentation

.github/workflows/documentation.yml

@@ -0,0 +1,36 @@
+name: Documentation
+
+on:
+  push:
+    tags:
+      - "*"
+
+env:
+  CPM_SOURCE_CACHE: ${{ github.workspace }}/cpm_modules
+
+jobs:
+  build:
+    name: Build and publish documentation
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: actions/cache@v3
+        with:
+          path: "**/cpm_modules"
+          key: ${{ github.workflow }}-cpm-modules-${{ hashFiles('**/CMakeLists.txt', '**/*.cmake') }}
+
+      - name: Install dependencies
+        run: |
+          choco install doxygen.install -y
+
+      - name: Build
+        run: |
+          cmake -S documentation -B build
+          cmake --build build --target GenerateDocs
+
+      - name: Publish
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./build/doxygen/html

cmake/CPM.cmake

@@ -0,0 +1,21 @@
+set(CPM_DOWNLOAD_VERSION 0.36.0)
+
+if(CPM_SOURCE_CACHE)
+    # Expand relative path. This is important if the provided path contains a tilde (~)
+    get_filename_component(CPM_SOURCE_CACHE ${CPM_SOURCE_CACHE} ABSOLUTE)
+    set(CPM_DOWNLOAD_LOCATION "${CPM_SOURCE_CACHE}/cpm/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
+elseif(DEFINED ENV{CPM_SOURCE_CACHE})
+    set(CPM_DOWNLOAD_LOCATION "$ENV{CPM_SOURCE_CACHE}/cpm/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
+else()
+    set(CPM_DOWNLOAD_LOCATION "${CMAKE_BINARY_DIR}/cmake/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
+endif()
+
+if(NOT (EXISTS ${CPM_DOWNLOAD_LOCATION}))
+    message(STATUS "Downloading CPM.cmake to ${CPM_DOWNLOAD_LOCATION}")
+    file(DOWNLOAD
+         https://github.com/cpm-cmake/CPM.cmake/releases/download/v${CPM_DOWNLOAD_VERSION}/CPM.cmake
+         ${CPM_DOWNLOAD_LOCATION}
+    )
+endif()
+
+include(${CPM_DOWNLOAD_LOCATION})

cmake/tools.cmake

@@ -0,0 +1,61 @@
+# this file contains a list of tools that can be activated and downloaded on-demand each tool is
+# enabled during configuration by passing an additional `-DUSE_<TOOL>=<VALUE>` argument to CMake
+
+# only activate tools for top level project
+if(NOT PROJECT_SOURCE_DIR STREQUAL CMAKE_SOURCE_DIR)
+    return()
+endif()
+
+include(${CMAKE_CURRENT_LIST_DIR}/CPM.cmake)
+
+# enables sanitizers support using the the `USE_SANITIZER` flag available values are: Address,
+# Memory, MemoryWithOrigins, Undefined, Thread, Leak, 'Address;Undefined'
+if(USE_SANITIZER OR USE_STATIC_ANALYZER)
+    CPMAddPackage("gh:StableCoder/cmake-scripts#1f822d1fc87c8d7720c074cde8a278b44963c354")
+
+    if(USE_SANITIZER)
+        include(${cmake-scripts_SOURCE_DIR}/sanitizers.cmake)
+    endif()
+
+    if(USE_STATIC_ANALYZER)
+        if("clang-tidy" IN_LIST USE_STATIC_ANALYZER)
+            set(CLANG_TIDY
+                ON
+                CACHE INTERNAL ""
+            )
+        else()
+            set(CLANG_TIDY
+                OFF
+                CACHE INTERNAL ""
+            )
+        endif()
+        if("iwyu" IN_LIST USE_STATIC_ANALYZER)
+            set(IWYU
+                ON
+                CACHE INTERNAL ""
+            )
+        else()
+            set(IWYU
+                OFF
+                CACHE INTERNAL ""
+            )
+        endif()
+        if("cppcheck" IN_LIST USE_STATIC_ANALYZER)
+            set(CPPCHECK
+                ON
+                CACHE INTERNAL ""
+            )
+        else()
+            set(CPPCHECK
+                OFF
+                CACHE INTERNAL ""
+            )
+        endif()
+
+        include(${cmake-scripts_SOURCE_DIR}/tools.cmake)
+
+        clang_tidy(${CLANG_TIDY_ARGS})
+        include_what_you_use(${IWYU_ARGS})
+        cppcheck(${CPPCHECK_ARGS})
+    endif()
+endif()

documentation/CMakeLists.txt

@@ -0,0 +1,29 @@
+cmake_minimum_required(VERSION 3.14 FATAL_ERROR)
+
+project(eventbusdocs)
+
+# ---- Dependencies ----
+
+include(../cmake/CPM.cmake)
+
+CPMAddPackage("gh:jothepro/doxygen-awesome-css#v1.6.1")
+CPMAddPackage(NAME eventbus SOURCE_DIR ${CMAKE_CURRENT_LIST_DIR}/../eventbus)
+find_package(Doxygen REQUIRED)
+
+# ---- Doxygen variables ----
+
+# set Doxyfile variables
+set(DOXYGEN_PROJECT_NAME eventbus)
+set(DOXYGEN_PROJECT_VERSION ${eventbus_VERSION})
+set(DOXYGEN_PROJECT_ROOT "${CMAKE_CURRENT_LIST_DIR}/../")
+set(DOXYGEN_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/doxygen")
+
+configure_file(${CMAKE_CURRENT_LIST_DIR}/Doxyfile ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+
+add_custom_target(
+    GenerateDocs
+    ${CMAKE_COMMAND} -E make_directory "${DOXYGEN_OUTPUT_DIRECTORY}"
+    COMMAND Doxygen::doxygen ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
+    COMMAND echo "Docs written to: ${DOXYGEN_OUTPUT_DIRECTORY}"
+    WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}"
+)

documentation/Doxyfile

@@ -0,0 +1,38 @@
+# Configuration for Doxygen for use with CMake
+# Only options that deviate from the default are included
+# To create a new Doxyfile containing all available options, call `doxygen -g`
+
+# Get Project name and version from CMake
+PROJECT_NAME = @DOXYGEN_PROJECT_NAME@
+PROJECT_NUMBER = @DOXYGEN_PROJECT_VERSION@
+
+# Add sources
+INPUT = @DOXYGEN_PROJECT_ROOT@/README.md @DOXYGEN_PROJECT_ROOT@/eventbus/include @DOXYGEN_PROJECT_ROOT@/documentation/pages
+EXCLUDE_PATTERNS = */test/* */detail/*
+EXTRACT_ALL = YES
+EXTRACT_PRIVATE = NO
+RECURSIVE = YES
+OUTPUT_DIRECTORY = @DOXYGEN_OUTPUT_DIRECTORY@
+
+# Use the README as a main page
+USE_MDFILE_AS_MAINPAGE = @DOXYGEN_PROJECT_ROOT@/README.md
+
+# set relative include paths
+FULL_PATH_NAMES = YES
+STRIP_FROM_PATH = @DOXYGEN_PROJECT_ROOT@/eventbus/include @DOXYGEN_PROJECT_ROOT@
+
+# We use m.css to generate the html documentation, so we only need XML output
+GENERATE_XML = NO
+GENERATE_HTML = YES
+GENERATE_LATEX = YES
+XML_PROGRAMLISTING = NO
+CREATE_SUBDIRS = YES
+
+HTML_EXTRA_STYLESHEET  = @doxygen-awesome-css_SOURCE_DIR@/doxygen-awesome.css
+HTML_COLORSTYLE_HUE    = 209
+HTML_COLORSTYLE_SAT    = 255
+HTML_COLORSTYLE_GAMMA  = 113
+GENERATE_TREEVIEW      = YES
+HAVE_DOT = YES
+DOT_IMAGE_FORMAT = svg
+EXAMPLE_PATH = @DOXYGEN_PROJECT_ROOT@/demo/