From 9488a66101ef9e1b4d45046a9e92b1602a2327f2 Mon Sep 17 00:00:00 2001 From: ReenigneArcher <42013603+ReenigneArcher@users.noreply.github.com> Date: Tue, 31 Mar 2026 20:47:19 -0400 Subject: [PATCH] docs: add doxygen --- .github/workflows/ci.yml | 20 +++++--- .gitmodules | 5 +- .readthedocs.yaml | 30 ++++++++++++ CMakeLists.txt | 8 ++++ README.md | 84 ++++++++++++++++++++++++++++++-- build.sh | 101 ++++++++++++++++++++------------------- docs/Doxyfile | 40 ++++++++++++++++ src/startup/video_mode.h | 40 ++++++++++++++++ third-party/doxyconfig | 1 + 9 files changed, 267 insertions(+), 62 deletions(-) create mode 100644 .readthedocs.yaml create mode 100644 docs/Doxyfile create mode 160000 third-party/doxyconfig diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 345acd8..256e4b8 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -63,7 +63,7 @@ jobs: - name: Setup Dependencies Linux if: runner.os == 'Linux' run: | - dependencies=( + nxdk_dependencies=( "bison" "build-essential" "clang" @@ -73,18 +73,24 @@ jobs: "lld" "llvm" ) + moonlight_dependencies=( + ) + dependencies=("${nxdk_dependencies[@]}" "${moonlight_dependencies[@]}") sudo apt-get update sudo apt-get install --no-install-recommends -y "${dependencies[@]}" - name: Setup Dependencies macOS if: runner.os == 'macOS' run: | - dependencies=( + nxdk_dependencies=( "cmake" "coreutils" "lld" "llvm" ) + moonlight_dependencies=( + ) + dependencies=("${nxdk_dependencies[@]}" "${moonlight_dependencies[@]}") brew install "${dependencies[@]}" - name: Setup Dependencies Windows @@ -94,15 +100,15 @@ jobs: msystem: MINGW64 update: true install: >- - make - cmake - git bison + cmake flex - mingw-w64-x86_64-gcc - mingw-w64-x86_64-llvm + git + make mingw-w64-x86_64-clang + mingw-w64-x86_64-gcc mingw-w64-x86_64-lld + mingw-w64-x86_64-llvm - name: Setup python id: setup-python diff --git a/.gitmodules b/.gitmodules index f30647d..52ccd50 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,7 +1,10 @@ +[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 - branch = main [submodule "third-party/moonlight-common-c"] path = third-party/moonlight-common-c url = https://github.com/moonlight-stream/moonlight-common-c.git diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..ee2f3bb --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,30 @@ +--- +# .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: + - | + if [ -f readthedocs_build.sh ]; then + doxyconfig_dir="." + else + doxyconfig_dir="./third-party/doxyconfig" + fi + chmod +x "${doxyconfig_dir}/readthedocs_build.sh" + export DOXYCONFIG_DIR="${doxyconfig_dir}" + "${doxyconfig_dir}/readthedocs_build.sh" + +# 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 index 7174459..224b727 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -18,6 +18,7 @@ set(XBOX_ISO "${CMAKE_PROJECT_NAME}.iso") # # Options # +option(BUILD_DOCS "Build documentation" ON) option(BUILD_TESTS "Build tests" OFF) # add custom modules @@ -101,6 +102,13 @@ target_link_libraries(${CMAKE_PROJECT_NAME} PUBLIC target_compile_definitions(${CMAKE_PROJECT_NAME} PRIVATE "") add_dependencies(${CMAKE_PROJECT_NAME} moonlight-common-c) +# +# documentation +# +if(BUILD_DOCS) + add_subdirectory(third-party/doxyconfig docs) +endif() + # # tests # diff --git a/README.md b/README.md index e951672..d3e38b2 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ Nothing works, except the splash screen. ## Build -### Pre-Build +### Prerequisites 1. Clone the repository with submodules, or update them after cloning. @@ -21,7 +21,78 @@ Nothing works, except the splash screen. git submodule update --init --recursive ``` -2. Install nxdk prerequisites. Then run the following from mingw64 or bash shell: +2. Install nxdk prerequisites. + +#### Windows + +> [!NOTE] +> You must use the mingw64 shell on Windows. + +```bash +pacman -Syu +nxdk_dependencies=( + "bison" + "cmake" + "flex" + "git" + "make" + "mingw-w64-x86_64-clang" + "mingw-w64-x86_64-gcc" + "mingw-w64-x86_64-lld" + "mingw-w64-x86_64-llvm" +) +moonlight_dependencies=( + "mingw-w64-x86_64-doxygen" + "mingw-w64-x86_64-graphviz" + "mingw-w64-ucrt-x86_64-nodejs" +) +dependencies=("${nxdk_dependencies[@]}" "${moonlight_dependencies[@]}") +pacman -S "${dependencies[@]}" +``` + +#### Debian/Ubuntu Linux + +```bash +nxdk_dependencies=( + "bison" + "build-essential" + "clang" + "cmake" + "flex" + "git" + "lld" + "llvm" +) +moonlight_dependencies=( + "doxygen" + "graphviz" + "nodejs" +) +dependencies=("${nxdk_dependencies[@]}" "${moonlight_dependencies[@]}") +apt install "${dependencies[@]}" +``` + +#### macOS + +```bash +nxdk_dependencies=( + "cmake" + "coreutils" + "lld" + "llvm" +) +moonlight_dependencies=( + "doxygen" + "graphviz" + "node" +) +dependencies=("${nxdk_dependencies[@]}" "${moonlight_dependencies[@]}") +brew install "${dependencies[@]}" +``` + +### Pre-Build + +1. Run the following from mingw64 or bash shell: ```bash export NXDK_DIR="$(pwd)/third-party/nxdk" @@ -102,7 +173,7 @@ If you only want the emulator without the ROM/HDD support bundle, run: scripts\setup-xemu.cmd --skip-support-files ``` -## Todo: +## Todo - Build - [x] Build in GitHub CI @@ -147,4 +218,9 @@ scripts\setup-xemu.cmd --skip-support-files - [ ] Save config and pairing states, probably use nlohmann/json - [ ] Host pairing - [ ] Possibly, GPU overclocking, see https://github.com/GXTX/XboxOverclock - - [ ] Docs via doxygen + - [x] Docs via doxygen + +
+ + [TOC] +
diff --git a/build.sh b/build.sh index bc853fd..490437a 100644 --- a/build.sh +++ b/build.sh @@ -4,8 +4,8 @@ set -euo pipefail usage() { - echo "Usage: $0 [--build-dir | ] [--clean|clean] [--distclean|distclean]" - return 0 + echo "Usage: $0 [--build-dir | ] [--clean|clean] [--distclean|distclean]" + return 0 } PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" @@ -15,59 +15,59 @@ DISTCLEAN_BUILD=0 POSITIONAL_BUILD_DIR_SET=0 while [[ "$#" -gt 0 ]]; do - case "$1" in - --build-dir|-B) - if [[ "$#" -lt 2 ]]; then - usage - exit 1 - fi - BUILD_DIR="$2" - POSITIONAL_BUILD_DIR_SET=1 - shift 2 - ;; - --clean|clean) - CLEAN_BUILD=1 - shift - ;; - --distclean|distclean) - DISTCLEAN_BUILD=1 - CLEAN_BUILD=1 - shift - ;; - -h|--help) - usage - exit 0 - ;; - *) - if [[ "${POSITIONAL_BUILD_DIR_SET}" -eq 0 ]]; then - BUILD_DIR="$1" - POSITIONAL_BUILD_DIR_SET=1 - shift - else - echo "Unknown argument: $1" - usage - exit 1 - fi - ;; - esac + case "$1" in + --build-dir|-B) + if [[ "$#" -lt 2 ]]; then + usage + exit 1 + fi + BUILD_DIR="$2" + POSITIONAL_BUILD_DIR_SET=1 + shift 2 + ;; + --clean|clean) + CLEAN_BUILD=1 + shift + ;; + --distclean|distclean) + DISTCLEAN_BUILD=1 + CLEAN_BUILD=1 + shift + ;; + -h|--help) + usage + exit 0 + ;; + *) + if [[ "${POSITIONAL_BUILD_DIR_SET}" -eq 0 ]]; then + BUILD_DIR="$1" + POSITIONAL_BUILD_DIR_SET=1 + shift + else + echo "Unknown argument: $1" + usage + exit 1 + fi + ;; + esac done case "${BUILD_DIR}" in - /*) - BUILD_DIR_PATH="${BUILD_DIR}" - ;; - *) - BUILD_DIR_PATH="${PROJECT_ROOT}/${BUILD_DIR}" - ;; + /*) + BUILD_DIR_PATH="${BUILD_DIR}" + ;; + *) + BUILD_DIR_PATH="${PROJECT_ROOT}/${BUILD_DIR}" + ;; esac # Set the NXDK_DIR environment variable export NXDK_DIR="${NXDK_DIR:-${PROJECT_ROOT}/third-party/nxdk}" if [[ ! -d "${NXDK_DIR}" ]]; then - echo "NXDK directory not found: ${NXDK_DIR}" - echo "Run: git submodule update --init --recursive" - exit 1 + echo "NXDK directory not found: ${NXDK_DIR}" + echo "Run: git submodule update --init --recursive" + exit 1 fi # Activate the nxdk environment @@ -77,7 +77,7 @@ eval "$("${NXDK_DIR}/bin/activate" -s)" cd "${NXDK_DIR}" if [[ "${DISTCLEAN_BUILD}" -eq 1 ]]; then - make distclean + make distclean fi # Build nxdk with the specified options @@ -87,7 +87,7 @@ make tools cd "${PROJECT_ROOT}" if [[ "${CLEAN_BUILD}" -eq 1 ]]; then - rm -rf "${BUILD_DIR_PATH}" + rm -rf "${BUILD_DIR_PATH}" fi # Configure the project @@ -95,8 +95,9 @@ cmake \ -G "Unix Makefiles" \ -B "${BUILD_DIR_PATH}" \ -S . \ - -DCMAKE_TOOLCHAIN_FILE="${NXDK_DIR}/share/toolchain-nxdk.cmake" \ - -DCMAKE_DEPENDS_USE_COMPILER=FALSE + -DBUILD_DOCS=OFF \ + -DCMAKE_TOOLCHAIN_FILE="${NXDK_DIR}/share/toolchain-nxdk.cmake" \ + -DCMAKE_DEPENDS_USE_COMPILER=FALSE # Build the project cmake --build "${BUILD_DIR_PATH}" diff --git a/docs/Doxyfile b/docs/Doxyfile new file mode 100644 index 0000000..fb20ca7 --- /dev/null +++ b/docs/Doxyfile @@ -0,0 +1,40 @@ +# 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] + +# project metadata +DOCSET_BUNDLE_ID = dev.lizardbyte.Moonlight-XboxOG +DOCSET_PUBLISHER_ID = dev.lizardbyte.Moonlight-XboxOG.documentation +PROJECT_BRIEF = "Moonlight Xbox OG is a port of the Moonlight Game Streaming client to the original Xbox console." +PROJECT_NAME = Moonlight-XboxOG + +# project specific settings +DOT_GRAPH_MAX_NODES = 50 +IMAGE_PATH = ../docs/images +INCLUDE_PATH = +PREDEFINED += NXDK + +# 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/src/startup/video_mode.h b/src/startup/video_mode.h index 70da3ef..4573300 100644 --- a/src/startup/video_mode.h +++ b/src/startup/video_mode.h @@ -8,12 +8,52 @@ namespace startup { + /** + * @brief Represents the set of available video modes and the chosen best mode. + * + * This structure is used during startup to collect detected video modes supported + * by the hardware and to store the best candidate selected by the detection + * algorithm. + */ struct VideoModeSelection { + /** + * @brief List of detected, available video modes. + * + * The vector contains VIDEO_MODE entries returned by the platform video + * subsystem. The detection code fills this list and then chooses a + * preferred mode to populate @c bestVideoMode. + */ std::vector availableVideoModes; + + /** + * @brief The selected best video mode from @c availableVideoModes. + * + * This is the mode chosen by the selection logic as the most suitable + * for the current configuration (color depth, refresh rate, etc.). If no + * suitable mode could be chosen, this value may be left as the default + * VIDEO_MODE value. + */ VIDEO_MODE bestVideoMode; }; + /** + * @brief Detect and choose the best available video mode. + * + * @param bpp Desired bits-per-pixel (color depth). Default is 32. + * @param refresh Desired refresh rate or REFRESH_DEFAULT to accept default. + * @return A VideoModeSelection containing the list of available modes and the + * selected best mode. + */ VideoModeSelection select_best_video_mode(int bpp = 32, int refresh = REFRESH_DEFAULT); + + /** + * @brief Log information about available and selected video modes. + * + * This function emits diagnostic information (e.g., to console or platform + * log) about the contents of the provided VideoModeSelection. + * + * @param selection The selection object to log. + */ void log_video_modes(const VideoModeSelection &selection); } // namespace startup diff --git a/third-party/doxyconfig b/third-party/doxyconfig new file mode 160000 index 0000000..a64e90d --- /dev/null +++ b/third-party/doxyconfig @@ -0,0 +1 @@ +Subproject commit a64e90d931d14aae023de913d60d9422c1b6cb2b