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,22 +1328,22 @@ 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
 # it.
 # 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,21 +1553,21 @@ 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
 # string, e.g. com.mycompany.MyDocSet.documentation.
 # 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,15 +2278,17 @@ 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
 # it.
 # 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 @@
 # 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,27 +122,22 @@
 
 # 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
 # https://github.com/readthedocs/readthedocs.org/blob/eadf6ac6dc6abc760a91e1cb147cc3c5f37d1ea8/docs/conf.py#L235-L236
 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 = doxy_proc.stdout.decode('utf-8').strip()
-print('doxygen version: ' + doxy_version)
+doxy_version = _run_subprocess(
+    args_list=['doxygen', '--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 @@
     )
 
 # run doxygen
-doxy_proc = subprocess.run('doxygen Doxyfile', shell=True, cwd=source_dir)
-if doxy_proc.returncode != 0:
-    raise RuntimeError('doxygen failed with return code ' + str(doxy_proc.returncode))
+doxy_proc = _run_subprocess(
+    args_list=['doxygen', 'Doxyfile'],
+    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::
-   :caption: src
-   :maxdepth: 1
-   :glob:
+Please refer to the `Doxygen Documentation <../doxyhtml/index.html>`_ for more details.
 
-   src/*
+.. todo:: Sphinx and Breathe do not support the Objective-C Domain.
+   See https://github.com/breathe-doc/breathe/issues/129
 
-.. toctree::
-   :caption: src/platform
-   :maxdepth: 1
-   :glob:
+.. .. doxygenindex::
+..    :allow-dot-graphs:
 
-   src/platform/*
-
-.. 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/*
+.. Ideally, we would use `doxygenfile` with `:allow-dot-graphs:`, but sphinx complains about duplicated namespaces...