docs: add doxygen docs

.codeql-prebuild-cpp-Linux.sh

@@ -21,7 +21,9 @@ sudo rm -rf /var/lib/apt/lists/*
 # build
 mkdir -p build
 cd build || exit 1
-cmake -G Ninja ..
+cmake \
+  -DBUILD_DOCS=OFF \
+  -G Ninja ..
 ninja
 
 # skip autobuild

.codeql-prebuild-cpp-Windows.sh

@@ -14,7 +14,9 @@ pacman --noconfirm -S \
 # build
 mkdir -p build
 cd build || exit 1
-cmake -G Ninja ..
+cmake \
+  -DBUILD_DOCS=OFF \
+  -G Ninja ..
 ninja
 
 # skip autobuild

.codeql-prebuild-cpp-macOS.sh

@@ -9,7 +9,9 @@ brew install \
 # build
 mkdir -p build
 cd build || exit 1
-cmake -G Ninja ..
+cmake \
+  -DBUILD_DOCS=OFF \
+  -G Ninja ..
 ninja
 
 # skip autobuild

.github/workflows/ci.yml

@@ -53,6 +53,8 @@ jobs:
           sudo apt-get install -y \
             build-essential \
             cmake \
+            doxygen \
+            graphviz \
             ${{ matrix.appindicator }} \
             libglib2.0-dev \
             libnotify-dev \
@@ -64,6 +66,8 @@ jobs:
         run: |
           brew install \
             cmake \
+            doxygen \
+            graphviz \
             ninja
 
       - name: Setup Dependencies Windows
@@ -73,8 +77,10 @@ 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-toolchain
 

.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,44 +1,71 @@
-# 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
 
-```
+```bash
 mkdir build
 cd build
 cmake -G Ninja ..
@@ -49,7 +76,7 @@ ninja
 
 Execute the `tray_example` application:
 
-```
+```bash
 ./tray_example
 ```
 
@@ -91,4 +118,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,42 @@
+# 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]
+
+# must be first
+DOXYFILE_ENCODING = UTF-8
+
+# 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

src/example.c

@@ -1,8 +1,12 @@
+/**
+ * @file src/example.c
+ * @brief Example usage of the tray library.
+ */
 #include <stdio.h>
 #include <string.h>
 
 #if defined (_WIN32) || defined (_WIN64)
-#define TRAY_WINAPI 1
+#define TRAY_WINAPI 1  ///< Use WinAPI.
 #elif defined (__linux__) || defined (linux) || defined (__linux)
 #define TRAY_APPINDICATOR 1
 #elif defined (__APPLE__) || defined (__MACH__)
@@ -18,8 +22,8 @@
 #define TRAY_ICON1 "icon.png"
 #define TRAY_ICON2 "icon.png"
 #elif TRAY_WINAPI
-#define TRAY_ICON1 "icon.ico"
-#define TRAY_ICON2 "icon.ico"
+#define TRAY_ICON1 "icon.ico"  ///< Path to first icon.
+#define TRAY_ICON2 "icon.ico"  ///< Path to second icon.
 #endif
 
 static struct tray tray;
@@ -92,6 +96,10 @@ static struct tray tray = {
             {.text = NULL}},
 };
 
+/**
+ * @brief Main entry point.
+ * @return 0 on success, 1 on error.
+ */
 int main() {
   if (tray_init(&tray) < 0) {
     printf("failed to create tray\n");