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..a2c132d --- /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/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 diff --git a/CMakeLists.txt b/CMakeLists.txt new file mode 100644 index 0000000..6276b8e --- /dev/null +++ b/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/Doxyfile b/Doxyfile new file mode 100644 index 0000000..bae4c47 --- /dev/null +++ b/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 += "admonition{2|}=@_admonition{\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{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
  • @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/README.md b/README.md index fd3e658..9fff642 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,29 @@ -# 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. Optionally, add the following to the input list in your Doxyfile. + + ```doxyfile + INPUT += ../third-party/doxyconfig/docs/source_code.md + ``` + +5. Optionally, copy the `.readthedocs.yaml` file to the root of your project. diff --git a/docs/source_code.md b/docs/source_code.md new file mode 100644 index 0000000..01f5156 --- /dev/null +++ b/docs/source_code.md @@ -0,0 +1,156 @@ +# Source Code + +Code should be documented using Doxygen syntax. + +## Guidelines + +### Doxygen Comments + +* Use Doxygen comments to document all files, functions, classes, and variables. +* [Inline documenation block](#inline-documentation-blocks) should use the following format: + + @verbatim +///< A brief description of the member. +@endverbatim + +* Multi-line comments, such as for a [documentation block](#documentation-blocks), should use the following format: + + @verbatim +/** +* @brief A brief description of the member. +* More detailed description of the member. +*/ +@endverbatim + +### Documentation Blocks + +Documentation blocks should be placed above the declaration of the function, class, or variable. Below is an example +of a documentation block for the main function. + +@verbatim +/** + * @brief Main application entry point. + * @param argc The number of arguments. + * @param argv The arguments. + * @return The exit code. + * @examples + * main(1, const char* args[] = {"hello", "markdown", nullptr}); + * @examples_end + */ +int main(int argc, char *argv[]); +@endverbatim + +@note The \@examples and \@examples_end tags are not standard Doxygen tags. They are custom aliases +we have specified to simplify documenting examples. Do not confuse this with the standard \@example tag. + +In some cases, it could be valuable to have slightly different documentation for the definitions, especially when +the definition may change depending on the platform or other factors. In such cases, you should put the documentation +that is common in the declaration and the definition-specific documentation in the definition. Below is an example of +how to document the declaration and definition of a function. + +@verbatim +// myFile.h +/** + * @brief A brief description of the function. + * @param arg1 Describe the first argument. + * @param arg2 Describe the second argument. + * @return Describe the result. + */ +int myFunction(int arg1, int arg2); + +// myFile.cpp +/** + * This describes anything which is specific to the implementation of the function. + */ +int myFunction(int arg1, int arg2) +{ + // Implementation +} +@endverbatim + +### File Documentation + +The file documentation block must be placed at the top of the file. If it is not present, Doxygen will ignore the file. +Understandably, it is difficult to make a creative description for every file, although it is still required. +Below is an example of a file documentation block. + +@verbatim +/** + * @file src/main.cpp + * @brief Main application entry point. + */ +@endverbatim + +### Inline Documentation Blocks + +Inline comments can be used to describe enum values, variables, and other code constructs. +To document the members of a file, struct, union, class, or enum, it is sometimes desired to place the documentation +block after the member instead of before. For this purpose you have to put an additional `<` marker in the comment +block. Below is an example of an inline comment for an enum value. + +@verbatim +enum class MyEnum +{ + FIRST_VALUE, ///< A brief description of the FIRST_VALUE + SECOND_VALUE ///< A brief description of the SECOND_VALUE +}; +@endverbatim + +### Custom Aliases + +We have defined some custom aliases to simplify documenting examples. + +* \@examples - Start of an example block. This will format the following text as `cpp`. +* \@examples_end - End of an example block. +* \@fa_icon{font awsome definition} - Insert a Font Awesome icon. Give the icon style and name as arguments. + e.g. \@fa_icon{fa-solid fa-check}. +* Admonitions + * \@admonition{Custom Title | Content } + @admonition{The one with the custom titles | It’s got a certain charm to it.} + * \@attention{Content} + @attention{The sun causes global warming.} + * \@caution{Content} + @caution{Cliff ahead: Don’t drive off it.} + * \@danger{Content} + @danger{Mad scientist at work!} + * \@error{Content} + @error{Does not compute.} + * \@hint{Content} + @hint{Insulators insulate, until they are subject to ______ voltage.} + * \@important{Content} + @important{Tech is not neutral, nor is it apolitical.} + * \@note{Content} + @note{This is a note.} + * \@seealso{Content} + @seealso{Other relevant information.} + * \@tip{Content} + @tip{25% if the service is good.} + * \@todo{Content} + @todo{Fix this.} + * \@warning{Content} + @warning{Reader discretion is strongly advised.} +* Tabs + @verbatim +@tabs{ + @tab{ Tab 1 Title | Tab 1 Content } + @tab{ Tab 2 Title | Tab 2 Content } +} +@endverbatim + @tabs{ + @tab{ Tab 1 Title | Tab 1 Content } + @tab{ Tab 2 Title | Tab 2 Content } + } +* Markers + * \@red{Content}
    + @red{This is red.} + * \@blue{Content}
    + @blue{This is blue.} + * \@green{Content}
    + @green{This is green.} + * \@yellow{Content}
    + @yellow{This is yellow.} +* Expander + @verbatim +@expander{Expander Title | Expander Content} +@endverbatim + @expander{Expander Title | Expander Content} 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 diff --git a/header.html b/header.html new file mode 100644 index 0000000..ee48c59 --- /dev/null +++ b/header.html @@ -0,0 +1,103 @@ + + + + + + + + +$projectname: $title +$title + + + + + + + + + +$treeview +$search +$mathjax +$darkmode + +$extrastylesheet + + + + + + + + + + + + + + + + + + + + + + +
    + + + +
    + + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    $projectname $projectnumber +
    +
    $projectbrief
    +     		+
    $projectbrief
    +     		$searchbox
    $searchbox
    +
    + + diff --git a/package.json b/package.json new file mode 100644 index 0000000..e7d63ad --- /dev/null +++ b/package.json @@ -0,0 +1,5 @@ +{ + "dependencies": { + "@fortawesome/fontawesome-free": "6.6.0" + } +}