diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..1ecaa0f --- /dev/null +++ b/.gitignore @@ -0,0 +1,6 @@ +# Ignore JetBrains IDE files +.idea/ + +# npm +node_modules/ +package-lock.json diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..f0f5637 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,4 @@ +[submodule "doxygen-awesome-css"] + path = doxygen-awesome-css + url = https://github.com/jothepro/doxygen-awesome-css.git + branch = main diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..d26125d --- /dev/null +++ b/.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/docs/Doxyfile ./docs/Doxyfile-doxyconfig + - cp ./third-party/doxyconfig/docs/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 diff --git a/README.md b/README.md index fd3e658..48ecde0 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,7 @@ -# template-base -Base repository template for LizardByte. +# doxyconfig + +This is a common Doxygen config for LizardByte projects. + +## Usage + +> TODO diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt new file mode 100644 index 0000000..6276b8e --- /dev/null +++ b/docs/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 +) diff --git a/docs/Doxyfile b/docs/Doxyfile new file mode 100644 index 0000000..1ed49ce --- /dev/null +++ b/docs/Doxyfile @@ -0,0 +1,124 @@ +# 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 +# + +# 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}=" +# admonitions +ALIASES += "_admonition{4|}=
@fa_icon{\3} \1
\4
" +# see: https://jothepro.github.io/doxygen-awesome-css/class_my_library_1_1_example.html#autotoc_md6 +ALIASES += "ad_admonition{2|}=@_admonition{\1 | todo | fa-solid fa-bars | \2}" +ALIASES += "ad_attention{1}=@_admonition{Attention | bug | fa-solid fa-triangle-exclamation | \1}" +ALIASES += "ad_caution{1}=@_admonition{Caution | section warning | fa-solid fa-triangle-exclamation | \1}" +ALIASES += "ad_danger{1}=@_admonition{Danger | bug | fa-solid fa-circle-exclamation | \1}" +ALIASES += "ad_error{1}=@_admonition{Error | bug | fa-solid fa-circle-xmark | \1}" +ALIASES += "ad_hint{1}=@_admonition{Hint | section pre | fa-solid fa-circle-question | \1}" +ALIASES += "ad_important{1}=@_admonition{Important | todo | fa-solid fa-fire | \1}" +ALIASES += "ad_note{1}=@_admonition{Note | section note | fa-solid fa-pencil | \1}" +ALIASES += "ad_seealso{1}=@_admonition{See also | section note | fa-solid fa-circle-info | \1}" +ALIASES += "ad_tip{1}=@_admonition{Tip | section pre | fa-solid fa-circle-info | \1}" +ALIASES += "ad_todo{1}=@_admonition{TODO | section deprecated | fa-solid fa-pencil | \1}" +ALIASES += "ad_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
  • @endhtmlonly^^\1^^@htmlonly@endhtmlonly^^\2^^@htmlonly
    • @endhtmlonly" +ALIASES += tabs{1}="@htmlonly

    @endhtmlonly" +# markers +ALIASES += red{1}="\1" +ALIASES += blue{1}="\1" +ALIASES += green{1}="\1" +ALIASES += yellow{1}="\1" +# expander +ALIASES += expander{2|}="@htmlonly
    ^^\1^^
    @endhtmlonly^^\2^^@htmlonly
    @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_NO_PARAMDOC = YES +WARNINGS = YES +XML_OUTPUT = xml + +# append the project specific settings here diff --git a/docs/header.html b/docs/header.html new file mode 100644 index 0000000..ee48c59 --- /dev/null +++ b/docs/header.html @@ -0,0 +1,103 @@ + + + + + + + + +$projectname: $title +$title + + + + + + + + + +$treeview +$search +$mathjax +$darkmode + +$extrastylesheet + + + + + + + + + + + + + + + + + + + + + + +
    + + + +
    + + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    $projectname $projectnumber +
    +
    $projectbrief
    +     		+
    $projectbrief
    +     		$searchbox
    $searchbox
    +
    + + diff --git a/docs/package.json b/docs/package.json new file mode 100644 index 0000000..e7d63ad --- /dev/null +++ b/docs/package.json @@ -0,0 +1,5 @@ +{ + "dependencies": { + "@fortawesome/fontawesome-free": "6.6.0" + } +} diff --git a/doxygen-awesome-css b/doxygen-awesome-css new file mode 160000 index 0000000..40e9b25 --- /dev/null +++ b/doxygen-awesome-css @@ -0,0 +1 @@ +Subproject commit 40e9b25b6174dd3b472d8868f63323a870dfeeb8 diff --git a/environment.yml b/environment.yml new file mode 100644 index 0000000..bdf9e46 --- /dev/null +++ b/environment.yml @@ -0,0 +1,9 @@ +--- +name: RTD +channels: + - conda-forge + - defaults +dependencies: + - doxygen=1.10.0 + - graphviz=11.0.0 + - nodejs