feat: initial version

.gitignore

@@ -0,0 +1,6 @@
+# Ignore JetBrains IDE files
+.idea/
+
+# npm
+node_modules/
+package-lock.json

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "doxygen-awesome-css"]
+	path = doxygen-awesome-css
+	url = https://github.com/jothepro/doxygen-awesome-css.git
+	branch = main

.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

@@ -0,0 +1,92 @@
+# find doxygen and graphviz
+find_package(Doxygen 1.10 REQUIRED dot)  # debian and ubuntu left in the dust
+
+# get parent project docs directory
+set(SOURCE_DOCS_DIR "${CMAKE_SOURCE_DIR}/docs")
+
+# fail if the directory does not exist
+if(NOT EXISTS ${SOURCE_DOCS_DIR})
+    message(FATAL_ERROR "Directory ${SOURCE_DOCS_DIR} does not exist")
+endif()
+
+# define variables based on whether we are building on readthedocs
+if(DEFINED ENV{READTHEDOCS})
+    set(DOXYGEN_BUILD_DIR_CMAKE $ENV{READTHEDOCS_OUTPUT})
+    set(DOXYGEN_PROJECT_VERSION $ENV{READTHEDOCS_VERSION})
+else()
+    set(DOXYGEN_BUILD_DIR_CMAKE "${CMAKE_CURRENT_BINARY_DIR}/build")
+    set(DOXYGEN_PROJECT_VERSION ${PROJECT_VERSION})
+endif()
+message(STATUS "DOXYGEN_BUILD_DIR_CMAKE: ${DOXYGEN_BUILD_DIR_CMAKE}")
+
+# create build directories, as doxygen fails to create it in some cases?
+file(MAKE_DIRECTORY "${DOXYGEN_BUILD_DIR_CMAKE}/html")
+
+# copy files to build directory
+file(COPY_FILE "${CMAKE_CURRENT_SOURCE_DIR}/header.html" "${SOURCE_DOCS_DIR}/header-doxyconfig.html")
+file(COPY_FILE "${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile" "${SOURCE_DOCS_DIR}/Doxyfile-doxyconfig")
+
+# append the "${SOURCE_DOCS_DIR}/Doxyfile to the Doxyfile-doxyconfig
+file(READ "${SOURCE_DOCS_DIR}/Doxyfile" DOXYFILE_CONTENTS)
+file(APPEND "${SOURCE_DOCS_DIR}/Doxyfile-doxyconfig" "${DOXYFILE_CONTENTS}")
+
+# sunshine has its own icon and logo
+if(NOT ${CMAKE_PROJECT_NAME} STREQUAL "Sunshine")
+    # download icon and logo
+    file(DOWNLOAD
+            "https://raw.githubusercontent.com/LizardByte/.github/master/branding/logos/favicon.ico"
+            "${DOXYGEN_BUILD_DIR_CMAKE}/lizardbyte.ico"
+    )
+    file(DOWNLOAD
+            "https://raw.githubusercontent.com/LizardByte/.github/master/branding/logos/logo-128x128.png"
+            "${DOXYGEN_BUILD_DIR_CMAKE}/lizardbyte.png"
+    )
+endif()
+
+# set FONT_AWESOME_FILES depends
+set(FONT_AWESOME_FILES_DEPENDS
+        "${CMAKE_CURRENT_SOURCE_DIR}/node_modules/@fortawesome/fontawesome-free/css/all.min.css"
+        "${CMAKE_CURRENT_SOURCE_DIR}/node_modules/@fortawesome/fontawesome-free/js/all.min.js"
+        "${CMAKE_CURRENT_SOURCE_DIR}/node_modules/@fortawesome/fontawesome-free/webfonts/"
+)
+
+find_program(NPM npm REQUIRED)
+add_custom_target(_docs_fontawesome_install
+        COMMENT "Installing node modules"
+        BYPRODUCTS ${FONT_AWESOME_FILES_DEPENDS}
+        COMMAND ${NPM} install
+        WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
+        VERBATIM
+)
+
+# copy Font Awesome files
+add_custom_command(
+        OUTPUT  FONT_AWESOME_FILES
+        COMMAND ${CMAKE_COMMAND}
+                -E copy ${CMAKE_CURRENT_SOURCE_DIR}/node_modules/@fortawesome/fontawesome-free/css/all.min.css
+                    ${DOXYGEN_BUILD_DIR_CMAKE}/html/assets/fontawesome/css/all.min.css
+        COMMAND ${CMAKE_COMMAND}
+                -E copy ${CMAKE_CURRENT_SOURCE_DIR}/node_modules/@fortawesome/fontawesome-free/js/all.min.js
+                    ${DOXYGEN_BUILD_DIR_CMAKE}/html/assets/fontawesome/js/all.min.js
+        COMMAND ${CMAKE_COMMAND}
+                -E copy_directory ${CMAKE_CURRENT_SOURCE_DIR}/node_modules/@fortawesome/fontawesome-free/webfonts
+                    ${DOXYGEN_BUILD_DIR_CMAKE}/html/assets/fontawesome/webfonts
+        COMMENT "Copying Font Awesome files"
+        DEPENDS ${FONT_AWESOME_FILES_DEPENDS}
+)
+
+# convert to relative path, so doxygen doesn't get confused on Windows
+file(RELATIVE_PATH DOXYGEN_BUILD_DIR_RELATIVE "${SOURCE_DOCS_DIR}" "${DOXYGEN_BUILD_DIR_CMAKE}")
+message(STATUS "DOXYGEN_BUILD_DIR_RELATIVE: ${DOXYGEN_BUILD_DIR_RELATIVE}")
+
+# build docs
+add_custom_target(docs ALL
+        COMMENT "Building Doxygen documentation"
+        WORKING_DIRECTORY "${SOURCE_DOCS_DIR}"
+        COMMAND ${CMAKE_COMMAND} -E env
+            READTHEDOCS_OUTPUT=${DOXYGEN_BUILD_DIR_RELATIVE}
+            READTHEDOCS_VERSION=${DOXYGEN_PROJECT_VERSION}
+            ${DOXYGEN_EXECUTABLE} Doxyfile-doxyconfig
+        VERBATIM
+        DEPENDS FONT_AWESOME_FILES
+)

Doxyfile

@@ -0,0 +1,131 @@
+# 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
+
+#
+# Common LizardByte settings
+#
+
+# LizardByte metadata
+DOCSET_PUBLISHER_NAME = LizardByte
+PROJECT_ICON = $(READTHEDOCS_OUTPUT)/lizardbyte.ico
+PROJECT_LOGO = $(READTHEDOCS_OUTPUT)/lizardbyte.png
+
+# doxygen-awesome-css
+HTML_COLORSTYLE = LIGHT  # required with Doxygen >= 1.9.5
+HTML_COLORSTYLE_HUE = 209
+HTML_COLORSTYLE_SAT = 255
+HTML_COLORSTYLE_GAMMA = 113
+HTML_COPY_CLIPBOARD = NO  # required for Doxygen >= 1.10.0
+HTML_EXTRA_FILES = ../third-party/doxyconfig/doxygen-awesome-css/doxygen-awesome-darkmode-toggle.js
+HTML_EXTRA_FILES += ../third-party/doxyconfig/doxygen-awesome-css/doxygen-awesome-fragment-copy-button.js
+HTML_EXTRA_FILES += ../third-party/doxyconfig/doxygen-awesome-css/doxygen-awesome-paragraph-link.js
+HTML_EXTRA_FILES += ../third-party/doxyconfig/doxygen-awesome-css/doxygen-awesome-interactive-toc.js
+HTML_EXTRA_FILES += ../third-party/doxyconfig/doxygen-awesome-css/doxygen-awesome-tabs.js
+HTML_EXTRA_STYLESHEET = ../third-party/doxyconfig/doxygen-awesome-css/doxygen-awesome.css
+HTML_HEADER = header-doxyconfig.html
+
+# custom aliases
+ALIASES = ""
+ALIASES += "examples=^^**Examples**^^@code{.cpp}"
+ALIASES += "examples_end=@endcode^^"
+# fontawsome
+ALIASES += "fa_icon{1}=<i class=\"\1\"></i>"
+# admonitions
+ALIASES += "_admonition{4|}=<dl class=\"\2\"><dt>@fa_icon{\3} \1</dt><dd>\4</dd></dl>"
+ALIASES += "_admonition_b{4|}=<dl class=\"\2\"><dt><b><a style=\"pointer-events: none; cursor: default;\" class=\"el\" href=\"\">@fa_icon{\3} \1</a></b></dt><dd>\4</dd></dl>"
+# see: https://jothepro.github.io/doxygen-awesome-css/class_my_library_1_1_example.html#autotoc_md6
+ALIASES += "admonition{2|}=@_admonition_b{\1 | todo | fa-solid fa-bars | \2}"
+ALIASES += "attention{1}=@_admonition{Attention | bug | fa-solid fa-triangle-exclamation | \1}"
+ALIASES += "caution{1}=@_admonition{Caution | section warning | fa-solid fa-triangle-exclamation | \1}"
+ALIASES += "danger{1}=@_admonition{Danger | bug | fa-solid fa-circle-exclamation | \1}"
+ALIASES += "error{1}=@_admonition{Error | bug | fa-solid fa-circle-xmark | \1}"
+ALIASES += "hint{1}=@_admonition{Hint | section pre | fa-solid fa-circle-question | \1}"
+ALIASES += "important{1}=@_admonition_b{Important | todo | fa-solid fa-fire | \1}"
+ALIASES += "note{1}=@_admonition{Note | section note | fa-solid fa-pencil | \1}"
+ALIASES += "seealso{1}=@_admonition{See also | section note | fa-solid fa-circle-info | \1}"
+ALIASES += "tip{1}=@_admonition{Tip | section pre | fa-solid fa-circle-info | \1}"
+ALIASES += "todo{1}=@_admonition{TODO | section deprecated | fa-solid fa-pencil | \1}"
+ALIASES += "warning{1}=@_admonition{Warning | section warning | fa-solid fa-triangle-exclamation | \1}"
+# tabs
+# see: https://github.com/jothepro/doxygen-awesome-css/discussions/146
+ALIASES += tab{2|}="@htmlonly<li><b class=\"tab-title\">@endhtmlonly^^\1^^@htmlonly</b>@endhtmlonly^^\2^^@htmlonly</li>@endhtmlonly"
+ALIASES += tabs{1}="@htmlonly<div class=\"tabbed\"><ul>@endhtmlonly^^\1^^@htmlonly</ul></div><br>@endhtmlonly"
+# markers
+ALIASES += red{1}="<span style=\"color:red\">\1</span>"
+ALIASES += blue{1}="<span style=\"color:blue\">\1</span>"
+ALIASES += green{1}="<span style=\"color:green\">\1</span>"
+ALIASES += yellow{1}="<span style=\"color:yellow\">\1</span>"
+# expander
+ALIASES += expander{2|}="@htmlonly<details><summary>^^\1^^</summary><div>@endhtmlonly^^\2^^@htmlonly</div></details>@endhtmlonly"
+
+# common predefined
+PREDEFINED = DOXYGEN
+PREDEFINED += __APPLE__
+PREDEFINED += linux
+PREDEFINED += __linux
+PREDEFINED += __linux__
+PREDEFINED += __MACH__
+PREDEFINED += _WIN32
+
+# general settings
+CASE_SENSE_NAMES = YES
+CREATE_SUBDIRS = NO
+DISABLE_INDEX = NO
+DOCBOOK_OUTPUT = docbook
+DOT_IMAGE_FORMAT = svg
+DOT_NUM_THREADS = 1
+EXTRACT_ALL = NO
+FULL_SIDEBAR = NO
+GENERATE_HTML = YES
+GENERATE_LATEX = NO
+GENERATE_TREEVIEW = YES
+GENERATE_XML = NO
+HAVE_DOT = YES
+HTML_OUTPUT = html
+INTERACTIVE_SVG = YES
+LATEX_OUTPUT = latex
+MACRO_EXPANSION = YES
+MAN_OUTPUT = man
+MARKDOWN_ID_STYLE = GITHUB
+MARKDOWN_SUPPORT = YES
+NUM_PROC_THREADS = 1
+PROJECT_NUMBER = $(READTHEDOCS_VERSION)
+OUTPUT_DIRECTORY = $(READTHEDOCS_OUTPUT)
+RECURSIVE = YES
+RTF_OUTPUT = rtf
+SORT_BRIEF_DOCS = YES
+STRIP_FROM_INC_PATH = ../
+STRIP_FROM_PATH = ../
+WARN_AS_ERROR = FAIL_ON_WARNINGS
+WARN_IF_DOC_ERROR = YES
+WARN_IF_INCOMPLETE_DOC = YES
+WARN_IF_UNDOC_ENUM_VAL = YES
+WARN_IF_UNDOCUMENTED = YES
+WARN_NO_PARAMDOC = YES
+WARNINGS = YES
+XML_OUTPUT = xml
+
+# append the project specific settings here

README.md

@@ -1,2 +1,36 @@
-# template-base
-Base repository template for LizardByte.
+# doxyconfig
+
+This is a common Doxygen config for LizardByte projects.
+
+## Usage
+
+1. Add this repository as a submodule to your project.
+
+   ```bash
+   git submodule add https://github.com/LizardByte/doxyconfig.git third-party/doxyconfig
+   ```
+
+2. Place project specific Doxyfile config in `./docs/Doxyfile`. You can overwrite anything from the common config here.
+3. Add the following to your CMakeLists.txt file.
+
+   ```cmake
+   option(BUILD_DOCS "Build documentation" ON)
+   if(BUILD_DOCS)
+       add_subdirectory(third-party/doxyconfig docs)
+   endif()
+   ```
+
+4. Add the following to your `.gitignore` file.
+
+   ```gitignore
+   # doxyconfig
+   docs/*-doxyconfig*
+   ```
+
+5. Optionally, add the following to the input list in your Doxyfile.
+
+   ```doxyfile
+   INPUT += ../third-party/doxyconfig/docs/source_code.md
+   ```
+
+6. Optionally, copy the `.readthedocs.yaml` file to the root of your project.