docs: use doxygen directly and drop breathe (#2739)

.codeql-prebuild-cpp-Windows.sh

@@ -19,6 +19,7 @@ pacman -Syu --noconfirm --ignore=mingw-w64-ucrt-x86_64-curl \
   gcc \
   git \
   make \
+  mingw-w64-ucrt-x86_64-boost \
   mingw-w64-ucrt-x86_64-cmake \
   mingw-w64-ucrt-x86_64-cppwinrt \
   mingw-w64-ucrt-x86_64-graphviz \

.github/workflows/CI.yml

@@ -990,9 +990,11 @@ jobs:
 
           # install dependencies
           pacman -U --noconfirm mingw-w64-ucrt-x86_64-curl-8.8.0-1-any.pkg.tar.zst
-          pacman -Syu --noconfirm --ignore=mingw-w64-ucrt-x86_64-curl \
+          pacman -Syu --noconfirm \
+            --ignore=mingw-w64-ucrt-x86_64-curl \
             doxygen \
             git \
+            mingw-w64-ucrt-x86_64-boost \
             mingw-w64-ucrt-x86_64-cmake \
             mingw-w64-ucrt-x86_64-cppwinrt \
             mingw-w64-ucrt-x86_64-graphviz \

.readthedocs.yaml

@@ -8,7 +8,7 @@ version: 2
 
 # Set the version of Python
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
     python: "3.11"
   apt_packages:

docs/Doxyfile

@@ -61,13 +61,13 @@ PROJECT_BRIEF          = "Sunshine is a Gamestream host for Moonlight."
 # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
 # the logo to the output directory.
 
-PROJECT_LOGO           = ../sunshine.png
+PROJECT_LOGO = ../sunshine.png
 
 # With the PROJECT_ICON tag one can specify an icon that is included in the tabs
 # when the HTML document is shown. Doxygen will copy the logo to the output
 # directory.
 
-PROJECT_ICON           =
+PROJECT_ICON = ../sunshine.ico
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
 # into which the generated documentation will be written. If a relative path is
@@ -1328,7 +1328,7 @@ IGNORE_PREFIX          =
 # If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output
 # The default value is: YES.
 
-GENERATE_HTML          = NO
+GENERATE_HTML = YES
 
 # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
@@ -1336,14 +1336,14 @@ GENERATE_HTML          = NO
 # The default directory is: html.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_OUTPUT            = doxyhtml
+HTML_OUTPUT = doxygen/doxyhtml
 
 # The HTML_FILE_EXTENSION tag can be used to specify the file extension for each
 # generated HTML page (for example: .htm, .php, .asp).
 # The default value is: .html.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_FILE_EXTENSION    = .html
+HTML_FILE_EXTENSION     = .html
 
 # The HTML_HEADER tag can be used to specify a user-defined HTML header file for
 # each generated HTML page. If the tag is left blank doxygen will generate a
@@ -1426,7 +1426,7 @@ HTML_EXTRA_FILES       =
 # The default value is: AUTO_LIGHT.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_COLORSTYLE        = AUTO_LIGHT
+HTML_COLORSTYLE = TOGGLE
 
 # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen
 # will adjust the colors in the style sheet and background images according to
@@ -1553,7 +1553,7 @@ DOCSET_FEEDURL         =
 # The default value is: org.doxygen.Project.
 # This tag requires that the tag GENERATE_DOCSET is set to YES.
 
-DOCSET_BUNDLE_ID       = org.doxygen.Project
+DOCSET_BUNDLE_ID = dev.lizardbyte.Sunshine
 
 # The DOCSET_PUBLISHER_ID tag specifies a string that should uniquely identify
 # the documentation publisher. This should be a reverse domain-name style
@@ -1561,13 +1561,13 @@ DOCSET_BUNDLE_ID       = org.doxygen.Project
 # The default value is: org.doxygen.Publisher.
 # This tag requires that the tag GENERATE_DOCSET is set to YES.
 
-DOCSET_PUBLISHER_ID    = org.doxygen.Publisher
+DOCSET_PUBLISHER_ID = dev.lizardbyte.Sunshine.documentation
 
 # The DOCSET_PUBLISHER_NAME tag identifies the documentation publisher.
 # The default value is: Publisher.
 # This tag requires that the tag GENERATE_DOCSET is set to YES.
 
-DOCSET_PUBLISHER_NAME  = Publisher
+DOCSET_PUBLISHER_NAME = LizardByte
 
 # If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three
 # additional HTML index files: index.hhp, index.hhc, and index.hhk. The
@@ -2278,7 +2278,9 @@ MAN_LINKS              = NO
 # captures the structure of the code including all documentation.
 # The default value is: NO.
 
-GENERATE_XML           = YES
+# TODO: Sphinx/Breathe does not support Objective-C right now, so disable XML
+# https://github.com/breathe-doc/breathe/issues/129
+GENERATE_XML = NO
 
 # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
@@ -2286,7 +2288,7 @@ GENERATE_XML           = YES
 # The default directory is: xml.
 # This tag requires that the tag GENERATE_XML is set to YES.
 
-XML_OUTPUT             = doxyxml
+XML_OUTPUT = doxygen/doxyxml
 
 # If the XML_PROGRAMLISTING tag is set to YES, doxygen will dump the program
 # listings (including syntax highlighting and cross-referencing information) to
@@ -2540,7 +2542,7 @@ HIDE_UNDOC_RELATIONS   = YES
 # set to NO
 # The default value is: NO.
 
-HAVE_DOT               = YES
+HAVE_DOT = YES
 
 # The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed
 # to run in parallel. When set to 0 doxygen will base this on the number of
@@ -2550,7 +2552,8 @@ HAVE_DOT               = YES
 # Minimum value: 0, maximum value: 32, default value: 0.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOT_NUM_THREADS        = 0
+# TODO: On Windows, Doxygen hangs when creating dot graphs if this is set to 0
+DOT_NUM_THREADS = 1
 
 # DOT_COMMON_ATTR is common attributes for nodes, edges and labels of
 # subgraphs. When you want a differently looking font in the dot files that
@@ -2765,7 +2768,7 @@ DIR_GRAPH_MAX_DEPTH    = 1
 # The default value is: png.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOT_IMAGE_FORMAT       = png
+DOT_IMAGE_FORMAT = svg
 
 # If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to
 # enable generation of interactive SVG images that allow zooming and panning.
@@ -2777,7 +2780,7 @@ DOT_IMAGE_FORMAT       = png
 # The default value is: NO.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-INTERACTIVE_SVG        = NO
+INTERACTIVE_SVG = YES
 
 # The DOT_PATH tag can be used to specify the path where the dot tool can be
 # found. If left blank, it is assumed the dot tool can be found in the path.

docs/requirements.txt

@@ -1,4 +1,3 @@
-breathe==4.35.0
 furo==2024.5.6
 m2r2==0.3.3.post2
 rstcheck[sphinx]==6.2.1

docs/source/conf.py

@@ -8,6 +8,51 @@
 from datetime import datetime
 import os
 import subprocess
+from typing import Mapping, Optional
+
+
+# re-usable functions
+def _run_subprocess(
+        args_list: list,
+        cwd: Optional[str] = None,
+        env: Optional[Mapping] = None,
+) -> bool:
+    og_dir = os.getcwd()
+    if cwd:
+        os.chdir(cwd)
+    process = subprocess.Popen(
+        args=args_list,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        cwd=cwd,
+        encoding='utf-8',
+        env=env,
+        errors='replace',
+    )
+
+    if cwd:
+        os.chdir(og_dir)
+
+    # Print stdout and stderr in real-time
+    # https://stackoverflow.com/a/57970619/11214013
+    while True:
+        realtime_output = process.stdout.readline()
+
+        if realtime_output == '' and process.poll() is not None:
+            break
+
+        if realtime_output:
+            print(realtime_output.strip(), flush=True)
+
+    process.stdout.close()
+
+    exit_code = process.wait()
+
+    if exit_code != 0:
+        print(f'::error:: Process [{args_list}] failed with exit code', exit_code)
+        raise RuntimeError(f'Process [{args_list}] failed with exit code {exit_code}')
+    else:
+        return True
 
 
 # -- Path setup --------------------------------------------------------------
@@ -35,11 +80,9 @@ version = os.getenv('READTHEDOCS_VERSION', 'dirty')
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'breathe',  # c++ support for sphinx with doxygen
     'm2r2',  # enable markdown files
     'sphinx.ext.autosectionlabel',
     'sphinx.ext.todo',  # enable to-do sections
-    'sphinx.ext.graphviz',  # enable graphs for breathe
     'sphinx.ext.viewcode',  # add links to view source code
     'sphinx_copybutton',  # add a copy button to code blocks
     'sphinx_inline_tabs',  # add tabs
@@ -79,12 +122,6 @@ html_theme_options = {
 
 # extension config options
 autosectionlabel_prefix_document = True  # Make sure the target is unique
-breathe_default_project = 'src'
-breathe_implementation_filename_extensions = ['.c', '.cc', '.cpp', '.mm']
-breathe_order_parameters_first = False
-breathe_projects = dict(
-    src="../build/doxyxml"
-)
 todo_include_todos = True
 
 # disable epub mimetype warnings
@@ -92,14 +129,15 @@ todo_include_todos = True
 suppress_warnings = ["epub.unknown_project_files"]
 
 # get doxygen version
-doxy_proc = subprocess.run('doxygen --version', shell=True, cwd=source_dir, capture_output=True)
+doxy_version = _run_subprocess(
-doxy_version = doxy_proc.stdout.decode('utf-8').strip()
+    args_list=['doxygen', '--version'],
-print('doxygen version: ' + doxy_version)
+    cwd=source_dir,
+)
 
 # create build directories, as doxygen fails to create it in macports and docker
 directories = [
     os.path.join(source_dir, 'build'),
-    os.path.join(source_dir, 'build', 'doxyxml'),
+    os.path.join(source_dir, 'build', 'doxygen', 'doxyhtml'),
 ]
 for d in directories:
     os.makedirs(
@@ -108,6 +146,12 @@ for d in directories:
     )
 
 # run doxygen
-doxy_proc = subprocess.run('doxygen Doxyfile', shell=True, cwd=source_dir)
+doxy_proc = _run_subprocess(
-if doxy_proc.returncode != 0:
+    args_list=['doxygen', 'Doxyfile'],
-    raise RuntimeError('doxygen failed with return code ' + str(doxy_proc.returncode))
+    cwd=source_dir
+)
+
+# copy doxygen html files
+html_extra_path = [
+    os.path.join(source_dir, 'build', 'doxygen'),  # the final directory is omitted in order to have a proper path
+]

docs/source/source_code/source_code.rst

@@ -55,37 +55,12 @@ Example Documentation Blocks
 Source
 ------
 
-.. toctree::
+Please refer to the `Doxygen Documentation <../doxyhtml/index.html>`_ for more details.
-   :caption: src
-   :maxdepth: 1
-   :glob:
 
-   src/*
+.. todo:: Sphinx and Breathe do not support the Objective-C Domain.
+   See https://github.com/breathe-doc/breathe/issues/129
 
-.. toctree::
+.. .. doxygenindex::
-   :caption: src/platform
+..    :allow-dot-graphs:
-   :maxdepth: 1
-   :glob:
 
-   src/platform/*
+.. Ideally, we would use `doxygenfile` with `:allow-dot-graphs:`, but sphinx complains about duplicated namespaces...
-
-.. toctree::
-   :caption: src/platform/linux
-   :maxdepth: 1
-   :glob:
-
-   src/platform/linux/*
-
-.. toctree::
-   :caption: src/platform/macos
-   :maxdepth: 1
-   :glob:
-
-   src/platform/macos/*
-
-.. toctree::
-   :caption: src/platform/windows
-   :maxdepth: 1
-   :glob:
-
-   src/platform/windows/*

docs/source/source_code/src/audio.rst

@@ -1,5 +0,0 @@
-audio
-=====
-
-.. doxygenfile:: audio.h
-   :allow-dot-graphs:

docs/source/source_code/src/cbs.rst

@@ -1,5 +0,0 @@
-cbs
-===
-
-.. doxygenfile:: cbs.h
-   :allow-dot-graphs:

docs/source/source_code/src/config.rst

@@ -1,5 +0,0 @@
-config
-======
-
-.. doxygenfile:: config.h
-   :allow-dot-graphs:

docs/source/source_code/src/confighttp.rst

@@ -1,5 +0,0 @@
-confighttp
-==========
-
-.. doxygenfile:: confighttp.h
-   :allow-dot-graphs:

docs/source/source_code/src/crypto.rst

@@ -1,5 +0,0 @@
-crypto
-======
-
-.. doxygenfile:: crypto.h
-   :allow-dot-graphs:

docs/source/source_code/src/entry_handler.rst

@@ -1,5 +0,0 @@
-entry_handler
-=============
-
-.. doxygenfile:: entry_handler.h
-   :allow-dot-graphs:

docs/source/source_code/src/file_handler.rst

@@ -1,5 +0,0 @@
-file_handler
-============
-
-.. doxygenfile:: file_handler.h
-   :allow-dot-graphs:

docs/source/source_code/src/globals.rst

@@ -1,5 +0,0 @@
-globals
-=======
-
-.. doxygenfile:: globals.h
-   :allow-dot-graphs:

docs/source/source_code/src/httpcommon.rst

@@ -1,5 +0,0 @@
-httpcommon
-==========
-
-.. doxygenfile:: httpcommon.h
-   :allow-dot-graphs:

docs/source/source_code/src/input.rst

@@ -1,5 +0,0 @@
-input
-=====
-
-.. doxygenfile:: input.h
-   :allow-dot-graphs:

docs/source/source_code/src/logging.rst

@@ -1,5 +0,0 @@
-logging
-=======
-
-.. doxygenfile:: logging.h
-   :allow-dot-graphs:

docs/source/source_code/src/main.rst

@@ -1,5 +0,0 @@
-main
-====
-
-.. doxygenfile:: main.h
-   :allow-dot-graphs:

docs/source/source_code/src/move_by_copy.rst

@@ -1,5 +0,0 @@
-move_by_copy
-============
-
-.. doxygenfile:: move_by_copy.h
-   :allow-dot-graphs:

docs/source/source_code/src/network.rst

@@ -1,5 +0,0 @@
-network
-=======
-
-.. doxygenfile:: network.h
-   :allow-dot-graphs:

docs/source/source_code/src/nvhttp.rst

@@ -1,5 +0,0 @@
-nvhttp
-======
-
-.. doxygenfile:: nvhttp.h
-   :allow-dot-graphs:

docs/source/source_code/src/platform/common.rst

@@ -1,4 +0,0 @@
-common
-======
-
-.. todo:: Add common.h

docs/source/source_code/src/platform/linux/cuda.rst

@@ -1,5 +0,0 @@
-cuda
-====
-
-.. doxygenfile:: platform/linux/cuda.h
-   :allow-dot-graphs:

docs/source/source_code/src/platform/linux/graphics.rst

@@ -1,4 +0,0 @@
-graphics
-========
-
-.. todo:: Add graphics.h

docs/source/source_code/src/platform/linux/misc.rst

@@ -1,4 +0,0 @@
-misc
-====
-
-.. todo:: Add misc.h

docs/source/source_code/src/platform/linux/vaapi.rst

@@ -1,5 +0,0 @@
-vaapi
-=====
-
-.. doxygenfile:: platform/linux/vaapi.h
-   :allow-dot-graphs:

docs/source/source_code/src/platform/linux/wayland.rst

@@ -1,5 +0,0 @@
-wayland
-=======
-
-.. doxygenfile:: platform/linux/wayland.h
-   :allow-dot-graphs:

docs/source/source_code/src/platform/linux/x11grab.rst

@@ -1,4 +0,0 @@
-x11grab
-=======
-
-.. todo:: Add x11grab.h

docs/source/source_code/src/platform/macos/av_audio.rst

@@ -1,4 +0,0 @@
-av_audio
-========
-
-.. todo:: Add av_audio.h

docs/source/source_code/src/platform/macos/av_img_t.rst

@@ -1,4 +0,0 @@
-av_img_t
-========
-
-.. todo:: Add av_img_t.h

docs/source/source_code/src/platform/macos/av_video.rst

@@ -1,4 +0,0 @@
-av_video
-========
-
-.. todo:: Add av_video.h

docs/source/source_code/src/platform/macos/misc.rst

@@ -1,5 +0,0 @@
-misc
-====
-
-.. doxygenfile:: platform/macos/misc.h
-   :allow-dot-graphs:

docs/source/source_code/src/platform/macos/nv12_zero_device.rst

@@ -1,4 +0,0 @@
-nv12_zero_device
-================
-
-.. todo:: Add nv12_zero_device.h

docs/source/source_code/src/platform/windows/PolicyConfig.rst

@@ -1,4 +0,0 @@
-PolicyConfig
-============
-
-.. todo:: Add PolicyConfig.h

docs/source/source_code/src/platform/windows/display.rst

@@ -1,4 +0,0 @@
-display
-=======
-
-.. todo:: Add display.h

docs/source/source_code/src/platform/windows/misc.rst

@@ -1,5 +0,0 @@
-misc
-====
-
-.. doxygenfile:: platform/windows/misc.h
-   :allow-dot-graphs:

docs/source/source_code/src/process.rst

@@ -1,5 +0,0 @@
-process
-=======
-
-.. doxygenfile:: process.h
-   :allow-dot-graphs:

docs/source/source_code/src/round_robin.rst

@@ -1,5 +0,0 @@
-round_robin
-===========
-
-.. doxygenfile:: round_robin.h
-   :allow-dot-graphs:

docs/source/source_code/src/rtsp.rst

@@ -1,5 +0,0 @@
-rtsp
-====
-
-.. doxygenfile:: rtsp.h
-   :allow-dot-graphs:

docs/source/source_code/src/stream.rst

@@ -1,5 +0,0 @@
-stream
-======
-
-.. doxygenfile:: stream.h
-   :allow-dot-graphs:

docs/source/source_code/src/sync.rst

@@ -1,5 +0,0 @@
-sync
-====
-
-.. doxygenfile:: sync.h
-   :allow-dot-graphs:

docs/source/source_code/src/system_tray.rst

@@ -1,5 +0,0 @@
-system_tray
-===========
-
-.. doxygenfile:: system_tray.h
-   :allow-dot-graphs:

docs/source/source_code/src/task_pool.rst

@@ -1,5 +0,0 @@
-task_pool
-=========
-
-.. doxygenfile:: task_pool.h
-   :allow-dot-graphs:

docs/source/source_code/src/thread_pool.rst

@@ -1,5 +0,0 @@
-thread_pool
-===========
-
-.. doxygenfile:: thread_pool.h
-   :allow-dot-graphs:

docs/source/source_code/src/thread_safe.rst

@@ -1,5 +0,0 @@
-thread_safe
-===========
-
-.. doxygenfile:: thread_safe.h
-   :allow-dot-graphs:

docs/source/source_code/src/upnp.rst

@@ -1,5 +0,0 @@
-upnp
-====
-
-.. doxygenfile:: upnp.h
-   :allow-dot-graphs:

docs/source/source_code/src/utility.rst

@@ -1,4 +0,0 @@
-utility
-=======
-
-.. todo:: Add utility.h

docs/source/source_code/src/uuid.rst

@@ -1,5 +0,0 @@
-uuid
-====
-
-.. doxygenfile:: uuid.h
-   :allow-dot-graphs:

docs/source/source_code/src/video.rst

@@ -1,5 +0,0 @@
-video
-=====
-
-.. doxygenfile:: video.h
-   :allow-dot-graphs: