diff --git a/.codeql-prebuild-cpp-Linux.sh b/.codeql-prebuild-cpp-Linux.sh index b75ad72..cf2507e 100644 --- a/.codeql-prebuild-cpp-Linux.sh +++ b/.codeql-prebuild-cpp-Linux.sh @@ -20,11 +20,12 @@ sudo rm -rf /var/lib/apt/lists/* # build mkdir -p build -cd build || exit 1 cmake \ -DBUILD_DOCS=OFF \ - -G Ninja .. -ninja + -B build \ + -G Ninja \ + -S . +ninja -C build # skip autobuild echo "skip_autobuild=true" >> "$GITHUB_OUTPUT" diff --git a/.codeql-prebuild-cpp-Windows.sh b/.codeql-prebuild-cpp-Windows.sh index 0527577..69c66c1 100644 --- a/.codeql-prebuild-cpp-Windows.sh +++ b/.codeql-prebuild-cpp-Windows.sh @@ -15,11 +15,12 @@ pacman --noconfirm -S \ # build mkdir -p build -cd build || exit 1 cmake \ -DBUILD_DOCS=OFF \ - -G Ninja .. -ninja + -B build \ + -G Ninja \ + -S . +ninja -C build # skip autobuild echo "skip_autobuild=true" >> "$GITHUB_OUTPUT" diff --git a/.codeql-prebuild-cpp-macOS.sh b/.codeql-prebuild-cpp-macOS.sh index 9233f3c..10d15da 100644 --- a/.codeql-prebuild-cpp-macOS.sh +++ b/.codeql-prebuild-cpp-macOS.sh @@ -10,11 +10,12 @@ brew install \ # build mkdir -p build -cd build || exit 1 cmake \ -DBUILD_DOCS=OFF \ - -G Ninja .. -ninja + -B build \ + -G Ninja \ + -S . +ninja -C build # skip autobuild echo "skip_autobuild=true" >> "$GITHUB_OUTPUT" diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d2914f3..34957c6 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -63,8 +63,6 @@ jobs: sudo apt-get install -y \ build-essential \ cmake \ - doxygen \ - graphviz \ ninja-build \ nlohmann-json3-dev @@ -72,12 +70,13 @@ jobs: if: runner.os == 'macOS' run: | brew install \ + boost \ cmake \ doxygen \ graphviz \ + nlohmann-json \ ninja \ - boost \ - nlohmann-json + node \ - name: Setup Dependencies Windows if: runner.os == 'Windows' @@ -91,6 +90,7 @@ jobs: 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 mingw-w64-ucrt-x86_64-boost mingw-w64-ucrt-x86_64-nlohmann-json @@ -177,18 +177,27 @@ jobs: COMMIT: ${{ needs.setup_release.outputs.release_commit }} run: | mkdir -p build - cd build + + 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 \ - .. - ninja + -S . + ninja -C build - name: Run tests id: test - working-directory: build + working-directory: build/tests run: | - ./tests/test_libdisplaydevice --gtest_color=yes + ./test_libdisplaydevice --gtest_color=yes - name: Generate gcov report # any except canceled or skipped diff --git a/.gitignore b/.gitignore index c75a6b1..9114397 100644 --- a/.gitignore +++ b/.gitignore @@ -41,5 +41,8 @@ build/ cmake-*/ +# doxyconfig +docs/*-doxyconfig* + # CTest Testing/ diff --git a/.gitmodules b/.gitmodules index 5d1e6f4..e3099df 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,7 +1,7 @@ -[submodule "third-party/doxygen-awesome-css"] - path = third-party/doxygen-awesome-css - url = https://github.com/jothepro/doxygen-awesome-css.git - branch = main +[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 diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 0d5a0cb..a2c132d 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -3,25 +3,37 @@ # Read the Docs configuration file # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details -# Required version: 2 -# Set the version of Python 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 docs/environment.yml - - conda env create --quiet --name $READTHEDOCS_VERSION --file docs/environment.yml - - cmake -B build -S . - - cmake --build build --target docs + - 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: docs/environment.yml + environment: third-party/doxyconfig/environment.yml submodules: include: all diff --git a/CMakeLists.txt b/CMakeLists.txt index 73497af..abe368b 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -16,7 +16,7 @@ if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES) endif() # Add our custom CMake modules to the global path -list(APPEND CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/cmake) +list(APPEND CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake") # # Project optional configuration @@ -28,7 +28,7 @@ option(BUILD_TESTS "Build tests" ON) # Documentation # if(BUILD_DOCS) - add_subdirectory(docs) + add_subdirectory(third-party/doxyconfig docs) endif() # diff --git a/README.md b/README.md index aafd57d..9d5419e 100644 --- a/README.md +++ b/README.md @@ -23,8 +23,7 @@ Ensure [git](https://git-scm.com/) is installed and run the following: ```bash git clone https://github.com/lizardbyte/libdisplaydevice.git --recurse-submodules cd libdisplaydevice -mkdir build -cd build +mkdir -p build ``` ### Windows @@ -54,18 +53,17 @@ pacman -S \ ### Build -> [!WARNING] -> Ensure you are in the build directory created during the clone step earlier before continuing. +@warning{Ensure you are in the build directory created during the clone step earlier before continuing.} ```bash -cmake -G Ninja .. -ninja +cmake -G Ninja -B build -S . +ninja -C build ``` ### Test ```bash -tests\test_libdisplaydevice +./build/tests/test_libdisplaydevice ``` ## Support diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt deleted file mode 100644 index e9eee5e..0000000 --- a/docs/CMakeLists.txt +++ /dev/null @@ -1,41 +0,0 @@ -# find doxygen and graphviz -find_package(Doxygen - REQUIRED dot) - -# 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}") - -# 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" -) - -# create build directories, as doxygen fails to create it in some cases? -file(MAKE_DIRECTORY "${DOXYGEN_BUILD_DIR_CMAKE}/html") - -# convert to relative path, so doxygen doesn't get confused on Windows -file(RELATIVE_PATH DOXYGEN_BUILD_DIR_RELATIVE "${CMAKE_CURRENT_SOURCE_DIR}" "${DOXYGEN_BUILD_DIR_CMAKE}") -message(STATUS "DOXYGEN_BUILD_DIR_RELATIVE: ${DOXYGEN_BUILD_DIR_RELATIVE}") - -# build docs -add_custom_target(docs ALL - WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" - COMMENT "Building Doxygen documentation" - COMMAND ${CMAKE_COMMAND} -E env - LDD_DOXYGEN_BUILD_DIR=${DOXYGEN_BUILD_DIR_RELATIVE} - LDD_PROJECT_VERSION=${DOXYGEN_PROJECT_VERSION} - ${DOXYGEN_EXECUTABLE} Doxyfile - VERBATIM -) diff --git a/docs/Doxyfile b/docs/Doxyfile index 115bcde..795908c 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -21,80 +21,22 @@ # replacement variables: # doxygen -x_noenv [configFile] -# must be first -DOXYFILE_ENCODING = UTF-8 - -# files and directories to process -INPUT = ../README.md \ - ../src - -ALIASES = "" -ALIASES += "examples=^^**Examples**^^@code{.cpp}" -ALIASES += "examples_end=@endcode^^" -ALIASES += "rst=^^\verbatim embed:rst:leading-asterisk^^" -ALIASES += "rst_end=\endverbatim" - -CASE_SENSE_NAMES = YES -DISABLE_INDEX = NO -DOCBOOK_OUTPUT = doxydocbook +# project metadata DOCSET_BUNDLE_ID = dev.lizardbyte.libdisplaydevice DOCSET_PUBLISHER_ID = dev.lizardbyte.libdisplaydevice.documentation -DOCSET_PUBLISHER_NAME = LizardByte -DOT_GRAPH_MAX_NODES = 50 -DOT_IMAGE_FORMAT = svg - -# TODO: On Windows, Doxygen hangs when creating dot graphs if this is set to 0 -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_COLORSTYLE = LIGHT # required with Doxygen >= 1.9.5 -HTML_COPY_CLIPBOARD = NO # required for Doxygen >= 1.10.0 -HTML_EXTRA_FILES = ../third-party/doxygen-awesome-css/doxygen-awesome-darkmode-toggle.js -HTML_EXTRA_FILES += ../third-party/doxygen-awesome-css/doxygen-awesome-fragment-copy-button.js -HTML_EXTRA_FILES += ../third-party/doxygen-awesome-css/doxygen-awesome-paragraph-link.js -HTML_EXTRA_FILES += ../third-party/doxygen-awesome-css/doxygen-awesome-interactive-toc.js -HTML_EXTRA_STYLESHEET = ../third-party/doxygen-awesome-css/doxygen-awesome.css -HTML_HEADER = doxygen/header.html -HTML_OUTPUT = html -# INCLUDE_PATH = ../ -INTERACTIVE_SVG = YES -LATEX_OUTPUT = latex -MACRO_EXPANSION = YES -MAN_OUTPUT = man -NUM_PROC_THREADS = 1 -PREDEFINED = DOXYGEN -PREDEFINED += __APPLE__ -PREDEFINED += linux -PREDEFINED += __linux -PREDEFINED += __linux__ -PREDEFINED += __MACH__ -PREDEFINED += _WIN32 PROJECT_BRIEF = "C++ library to modify display devices." -PROJECT_ICON = $(LDD_DOXYGEN_BUILD_DIR)/lizardbyte.ico -PROJECT_NUMBER = $(LDD_PROJECT_VERSION) -PROJECT_LOGO = $(LDD_DOXYGEN_BUILD_DIR)/lizardbyte.png PROJECT_NAME = libdisplaydevice -OUTPUT_DIRECTORY = $(LDD_DOXYGEN_BUILD_DIR) -RECURSIVE = YES -RTF_OUTPUT = rtf -SORT_BRIEF_DOCS = YES -STRIP_FROM_INC_PATH = ../ -STRIP_FROM_PATH = ../ -WARN_AS_ERROR = FAIL_ON_WARNINGS + +# project specific settings +DOT_GRAPH_MAX_NODES = 50 +# IMAGE_PATH = ../docs/images +INCLUDE_PATH = # TODO: Enable this when we have complete documentation WARN_IF_UNDOCUMENTED = NO -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 +# files and directories to process +USE_MDFILE_AS_MAINPAGE = ../README.md +INPUT = ../README.md \ + ../third-party/doxyconfig/docs/source_code.md \ + ../src diff --git a/docs/doxygen/header.html b/docs/doxygen/header.html deleted file mode 100644 index 774de74..0000000 --- a/docs/doxygen/header.html +++ /dev/null @@ -1,95 +0,0 @@ - - - - - - - - -$projectname: $title -$title - - - - - - - - - - -$treeview -$search -$mathjax -$darkmode - -$extrastylesheet - - - - - - - - - - - - - - - -
- - - -
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-
$projectname $projectnumber -
-
$projectbrief
-
-
$projectbrief
-
$searchbox
$searchbox
-
- - diff --git a/docs/environment.yml b/docs/environment.yml deleted file mode 100644 index ff274e0..0000000 --- a/docs/environment.yml +++ /dev/null @@ -1,12 +0,0 @@ ---- -name: RTD -channels: - - conda-forge - - defaults -dependencies: - - boost - - cmake - - doxygen=1.10.0 - - graphviz=11.0.0 - - ninja - - nlohmann_json diff --git a/third-party/doxyconfig b/third-party/doxyconfig new file mode 160000 index 0000000..671b494 --- /dev/null +++ b/third-party/doxyconfig @@ -0,0 +1 @@ +Subproject commit 671b494f3cbe8597a36d81869a864dc9fff497f4 diff --git a/third-party/doxygen-awesome-css b/third-party/doxygen-awesome-css deleted file mode 160000 index 40e9b25..0000000 --- a/third-party/doxygen-awesome-css +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 40e9b25b6174dd3b472d8868f63323a870dfeeb8