docs: add doxygen docs (#21)

Author: ReenigneArcher

.codeql-prebuild-cpp-Linux.sh

@@ -20,9 +20,12 @@ sudo rm -rf /var/lib/apt/lists/*
 
 # build
 mkdir -p build
-cd build || exit 1
-cmake -G Ninja ..
-ninja
+cmake \
+  -DBUILD_DOCS=OFF \
+  -B build \
+  -G Ninja \
+  -S .
+ninja -C build
 
 # skip autobuild
 echo "skip_autobuild=true" >> "$GITHUB_OUTPUT"

.codeql-prebuild-cpp-Windows.sh

@@ -13,9 +13,12 @@ pacman --noconfirm -S \
 
 # build
 mkdir -p build
-cd build || exit 1
-cmake -G Ninja ..
-ninja
+cmake \
+  -DBUILD_DOCS=OFF \
+  -B build \
+  -G Ninja \
+  -S .
+ninja -C build
 
 # skip autobuild
 echo "skip_autobuild=true" >> "$GITHUB_OUTPUT"

.codeql-prebuild-cpp-macOS.sh

@@ -8,9 +8,12 @@ brew install \
 
 # build
 mkdir -p build
-cd build || exit 1
-cmake -G Ninja ..
-ninja
+cmake \
+  -DBUILD_DOCS=OFF \
+  -B build \
+  -G Ninja \
+  -S .
+ninja -C build
 
 # skip autobuild
 echo "skip_autobuild=true" >> "$GITHUB_OUTPUT"

.github/workflows/ci.yml

@@ -64,7 +64,10 @@ jobs:
         run: |
           brew install \
             cmake \
-            ninja
+            doxygen \
+            graphviz \
+            ninja \
+            node
 
       - name: Setup Dependencies Windows
         if: runner.os == 'Windows'
@@ -73,9 +76,12 @@ jobs:
           msystem: ucrt64
           update: true
           install: >-
+            doxygen
             mingw-w64-ucrt-x86_64-binutils
             mingw-w64-ucrt-x86_64-cmake
+            mingw-w64-ucrt-x86_64-graphviz
             mingw-w64-ucrt-x86_64-ninja
+            mingw-w64-ucrt-x86_64-nodejs
             mingw-w64-ucrt-x86_64-toolchain
 
       - name: Setup python
@@ -101,20 +107,32 @@ jobs:
       - name: Build
         run: |
           mkdir -p build
-          cd build
-          cmake -DCMAKE_BUILD_TYPE:STRING=Debug -G Ninja ..
-          ninja
+
+          if [ "${{ runner.os }}" = "Linux" ]; then
+            # Doxygen from Ubuntu is too old, need Doxygen >= 1.10
+            DOCS=OFF
+          else
+            DOCS=ON
+          fi
+
+          cmake \
+            -DBUILD_DOCS=${DOCS} \
+            -DCMAKE_BUILD_TYPE:STRING=Debug \
+            -B build \
+            -G Ninja \
+            -S .
+          ninja -C build
 
       - name: Run tests
         id: test
-        working-directory: build
+        working-directory: build/tests
         run: |
           if [ "${{ runner.os }}" = "Linux" ]; then
             export DISPLAY=:1
             Xvfb ${DISPLAY} -screen 0 1024x768x24 &
           fi
 
-          ./tests/test_tray --gtest_color=yes
+          ./test_tray --gtest_color=yes
 
       - name: Generate gcov report
         # any except canceled or skipped

.gitignore

@@ -40,3 +40,6 @@
 # build directories
 build/
 cmake-*/
+
+# doxyconfig
+docs/*-doxyconfig*

.gitmodules

@@ -1,3 +1,7 @@
+[submodule "third-party/doxyconfig"]
+	path = third-party/doxyconfig
+	url = https://github.com/LizardByte/doxyconfig.git
+	branch = master
 [submodule "third-party/googletest"]
 	path = third-party/googletest
 	url = https://github.com/google/googletest.git

.readthedocs.yaml

@@ -0,0 +1,40 @@
+---
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "miniconda-latest"
+  commands:
+    # because we are overriding the build commands, we need to setup the environment ourselves
+    - cat third-party/doxyconfig/environment.yml
+    - conda env create --quiet --name ${READTHEDOCS_VERSION} --file third-party/doxyconfig/environment.yml
+    - npm install "@fortawesome/fontawesome-free"
+    - mkdir -p ${READTHEDOCS_OUTPUT}html/assets/fontawesome/css
+    - mkdir -p ${READTHEDOCS_OUTPUT}html/assets/fontawesome/js
+    - cp node_modules/@fortawesome/fontawesome-free/css/all.min.css ${READTHEDOCS_OUTPUT}html/assets/fontawesome/css
+    - cp node_modules/@fortawesome/fontawesome-free/js/all.min.js ${READTHEDOCS_OUTPUT}html/assets/fontawesome/js
+    - cp -r node_modules/@fortawesome/fontawesome-free/webfonts ${READTHEDOCS_OUTPUT}html/assets/fontawesome/
+    - |
+      wget "https://raw.githubusercontent.com/LizardByte/.github/master/branding/logos/favicon.ico" \
+        -O ${READTHEDOCS_OUTPUT}lizardbyte.ico
+    - |
+      wget "https://raw.githubusercontent.com/LizardByte/.github/master/branding/logos/logo-128x128.png" \
+        -O ${READTHEDOCS_OUTPUT}lizardbyte.png
+    - cp ./third-party/doxyconfig/Doxyfile ./docs/Doxyfile-doxyconfig
+    - cp ./third-party/doxyconfig/header.html ./docs/header-doxyconfig.html
+    - cat ./docs/Doxyfile >> ./docs/Doxyfile-doxyconfig
+    - cd docs && doxygen Doxyfile-doxyconfig
+
+# using conda, we can get newer doxygen and graphviz than ubuntu provide
+# https://github.com/readthedocs/readthedocs.org/issues/8151#issuecomment-890359661
+conda:
+  environment: third-party/doxyconfig/environment.yml
+
+submodules:
+  include: all
+  recursive: true

CMakeLists.txt

@@ -1,8 +1,11 @@
+#
+# Project configuration
+#
 cmake_minimum_required(VERSION 3.13 FATAL_ERROR) # target_link_directories
-
-project(tray
-        LANGUAGES C
-        DESCRIPTION "A cross-platform system tray library")
+project(tray VERSION 0.0.0
+        DESCRIPTION "A cross-platform system tray library"
+        HOMEPAGE_URL "https://app.lizardbyte.dev"
+        LANGUAGES C)
 
 set(PROJECT_LICENSE "MIT")
 
@@ -11,11 +14,22 @@ if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
     set(CMAKE_BUILD_TYPE "Release" CACHE STRING "Choose the type of build." FORCE)
 endif()
 
+# Add our custom CMake modules to the global path
 set(CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")
 
-# options
+#
+# Project optional configuration
+#
+option(BUILD_DOCS "Build documentation" ON)
 option(BUILD_TESTS "Build tests" ON)
 
+#
+# Documentation
+#
+if(BUILD_DOCS)
+    add_subdirectory(third-party/doxyconfig docs)
+endif()
+
 # Generate 'compile_commands.json' for clang_complete
 set(CMAKE_COLOR_MAKEFILE ON)
 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

README.md

@@ -1,56 +1,90 @@
-# Cross-platform Linux/macOS/Windows Tray
+# Overview
 
-[![codecov](https://img.shields.io/codecov/c/gh/LizardByte/tray?token=HSX66JNEOL&style=for-the-badge&logo=codecov&label=codecov)](https://codecov.io/gh/LizardByte/tray)
+[![GitHub Workflow Status (CI)](https://img.shields.io/github/actions/workflow/status/lizardbyte/tray/ci.yml.svg?branch=master&label=CI%20build&logo=github&style=for-the-badge)](https://github.com/LizardByte/tray/actions/workflows/ci.yml?query=branch%3Amaster)
+[![Codecov](https://img.shields.io/codecov/c/gh/LizardByte/tray?token=HSX66JNEOL&style=for-the-badge&logo=codecov&label=codecov)](https://codecov.io/gh/LizardByte/tray)
+[![GitHub stars](https://img.shields.io/github/stars/lizardbyte/tray.svg?logo=github&style=for-the-badge)](https://github.com/LizardByte/tray)
 
-<img src="docs/images/screenshot_macosx.png">
+## About
 
-<img src="docs/images/screenshot_windows.png">
+Cross-platform, super tiny C99 implementation of a system tray icon with a popup menu and notifications.
 
-<img src="docs/images/screenshot_linux.png">
+The code is C++ friendly and will compile fine in C++98 and up. This is a fork of
+[dmikushin/tray](https://github.com/dmikushin/tray) and is intended to add additional features required for our own
+[Sunshine](https://github.com/LizardByte/Sunshine) project.
 
-Cross-platform, super tiny C99 implementation of a system tray icon with a popup menu.
+This fork adds the following features:
 
-Works well on:
+- system tray notifications
+- support for both linux appindicator versions
+- unit tests
+- code coverage
+- refactored code, e.g. moved source code into the `src` directory
+- doxygen documentation, and readthedocs configuration
+
+## Screenshots
+
+<div class="tabbed">
+
+- <b class="tab-title">Linux</b>![linux](docs/images/screenshot_linux.png)
+- <b class="tab-title">macOS</b>![macOS](docs/images/screenshot_macos.png)
+- <b class="tab-title">Windows</b>![windows](docs/images/screenshot_windows.png)
+
+</div>
+
+## Supported platforms
 
 * Linux/Gtk (libayatana-appindicator3 or libappindicator3)
 * Windows XP or newer (shellapi.h)
 * MacOS (Cocoa/AppKit)
 
-The code is C++ friendly and will compile fine in C++98 and up.
+## Prerequisites
 
-This fork is intended to bring together the [original work of Serge Zaitsev](https://github.com/zserge/tray) and the most interesting forks and PRs of respectable contributors:
+* CMake
+* [Ninja](https://ninja-build.org/), in order to have the same build commands on all platforms 
 
-* [Only process messages coming from the tray window on Windows](https://github.com/zserge/tray/pull/18)
-* [Become C++-friendly](https://github.com/zserge/tray/pull/16)
-* [Fix all menu items have a check box](https://github.com/zserge/tray/pull/11)
-* [Add support for tooltip](https://github.com/zserge/tray/pull/11)
-* Darwin implementation translated from C to Objective C adapted from [@trevex fork](https://github.com/trevex/tray)
+### Linux Dependencies
 
-## Prerequisites
+<div class="tabbed">
 
-* CMake
-* [Ninja](https://ninja-build.org/), in order to have the same build commands on all platforms
-* AppIndicator on Linux:
+- <b class="tab-title">Arch</b>
+    ```bash
+    sudo pacman -S libayatana-appindicator
+    ```
 
-```
-sudo apt install libappindicator3-dev
-```
+- <b class="tab-title">Debian/Ubuntu</b>
+    ```bash
+    sudo apt install libappindicator3-dev
+    ```
+
+- <b class="tab-title">Fedora</b>
+    ```bash
+    sudo dnf install libappindicator-gtk3-devel
+    ```
+
+</div>
 
 ## Building
 
-```
-mkdir build
-cd build
-cmake -G Ninja ..
-ninja
+```bash
+mkdir -p build
+cmake -G Ninja -B build -S .
+ninja -C build
 ```
 
 ## Demo
 
 Execute the `tray_example` application:
 
+```bash
+./build/tray_example
 ```
-./tray_example
+
+## Tests
+
+Execute the `tests` application:
+
+```bash
+./build/tests/test_tray
 ```
 
 ## API
@@ -91,4 +125,4 @@ array must have text field set to NULL.
 ## License
 
 This software is distributed under [MIT license](http://www.opensource.org/licenses/mit-license.php),
- so feel free to integrate it in your commercial products.
+so feel free to integrate it in your commercial products.

docs/Doxyfile

@@ -0,0 +1,39 @@
+# This file describes the settings to be used by the documentation system
+# doxygen (www.doxygen.org) for a project.
+#
+# All text after a double hash (##) is considered a comment and is placed in
+# front of the TAG it is preceding.
+#
+# All text after a single hash (#) is considered a comment and will be ignored.
+# The format is:
+# TAG = value [value, ...]
+# For lists, items can also be appended using:
+# TAG += value [value, ...]
+# Values that contain spaces should be placed between quotes (\" \").
+#
+# Note:
+#
+# Use doxygen to compare the used configuration file with the template
+# configuration file:
+# doxygen -x [configFile]
+# Use doxygen to compare the used configuration file with the template
+# configuration file without replacing the environment variables or CMake type
+# replacement variables:
+# doxygen -x_noenv [configFile]
+
+# project metadata
+DOCSET_BUNDLE_ID = dev.lizardbyte.tray
+DOCSET_PUBLISHER_ID = dev.lizardbyte.tray.documentation
+PROJECT_BRIEF = "Cross-platform, super tiny C99 implementation of a system tray icon with a popup menu and notifications."
+PROJECT_NAME = tray
+
+# project specific settings
+DOT_GRAPH_MAX_NODES = 50
+IMAGE_PATH = ../docs/images
+INCLUDE_PATH =
+
+# files and directories to process
+USE_MDFILE_AS_MAINPAGE = ../README.md
+INPUT = ../README.md \
+        ../third-party/doxyconfig/docs/source_code.md \
+        ../src