docs: use doxygen directly and drop breathe

LizardByte · Jun 21, 2024 · a205598 · a205598
1 parent acd9ae6
commit a205598
Show file tree

Hide file tree

Showing 47 changed files with 21 additions and 244 deletions.
diff --git a/docs/Doxyfile b/docs/Doxyfile
@@ -1328,15 +1328,15 @@ 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 = doxyhtml/doxyhtml
 
 # The HTML_FILE_EXTENSION tag can be used to specify the file extension for each
 # generated HTML page (for example: .htm, .php, .asp).
@@ -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 = AUTO_DARK
 
 # 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,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

diff --git a/docs/requirements.txt b/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

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -35,7 +35,6 @@
 # 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
@@ -100,6 +99,7 @@
 directories = [
     os.path.join(source_dir, 'build'),
     os.path.join(source_dir, 'build', 'doxyxml'),
+    os.path.join(source_dir, 'build', 'doxyhtml', 'doxyhtml'),
 ]
 for d in directories:
     os.makedirs(
@@ -111,3 +111,8 @@
 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))
+
+# copy doxygen html files
+html_extra_path = [
+    os.path.join(source_dir, 'build', 'doxyhtml'),  # the final directory is omitted in order to have a proper path
+]
diff --git a/docs/source/source_code/source_code.rst b/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...
diff --git a/docs/source/source_code/src/audio.rst b/docs/source/source_code/src/audio.rst
diff --git a/docs/source/source_code/src/cbs.rst b/docs/source/source_code/src/cbs.rst
diff --git a/docs/source/source_code/src/config.rst b/docs/source/source_code/src/config.rst
diff --git a/docs/source/source_code/src/confighttp.rst b/docs/source/source_code/src/confighttp.rst
diff --git a/docs/source/source_code/src/crypto.rst b/docs/source/source_code/src/crypto.rst
diff --git a/docs/source/source_code/src/entry_handler.rst b/docs/source/source_code/src/entry_handler.rst
diff --git a/docs/source/source_code/src/file_handler.rst b/docs/source/source_code/src/file_handler.rst
diff --git a/docs/source/source_code/src/globals.rst b/docs/source/source_code/src/globals.rst
diff --git a/docs/source/source_code/src/httpcommon.rst b/docs/source/source_code/src/httpcommon.rst
diff --git a/docs/source/source_code/src/input.rst b/docs/source/source_code/src/input.rst
diff --git a/docs/source/source_code/src/logging.rst b/docs/source/source_code/src/logging.rst
diff --git a/docs/source/source_code/src/main.rst b/docs/source/source_code/src/main.rst
diff --git a/docs/source/source_code/src/move_by_copy.rst b/docs/source/source_code/src/move_by_copy.rst
diff --git a/docs/source/source_code/src/network.rst b/docs/source/source_code/src/network.rst
diff --git a/docs/source/source_code/src/nvhttp.rst b/docs/source/source_code/src/nvhttp.rst
diff --git a/docs/source/source_code/src/platform/common.rst b/docs/source/source_code/src/platform/common.rst
diff --git a/docs/source/source_code/src/platform/linux/cuda.rst b/docs/source/source_code/src/platform/linux/cuda.rst
diff --git a/docs/source/source_code/src/platform/linux/graphics.rst b/docs/source/source_code/src/platform/linux/graphics.rst
diff --git a/docs/source/source_code/src/platform/linux/misc.rst b/docs/source/source_code/src/platform/linux/misc.rst
diff --git a/docs/source/source_code/src/platform/linux/vaapi.rst b/docs/source/source_code/src/platform/linux/vaapi.rst
diff --git a/docs/source/source_code/src/platform/linux/wayland.rst b/docs/source/source_code/src/platform/linux/wayland.rst
diff --git a/docs/source/source_code/src/platform/linux/x11grab.rst b/docs/source/source_code/src/platform/linux/x11grab.rst
diff --git a/docs/source/source_code/src/platform/macos/av_audio.rst b/docs/source/source_code/src/platform/macos/av_audio.rst
diff --git a/docs/source/source_code/src/platform/macos/av_img_t.rst b/docs/source/source_code/src/platform/macos/av_img_t.rst
diff --git a/docs/source/source_code/src/platform/macos/av_video.rst b/docs/source/source_code/src/platform/macos/av_video.rst
diff --git a/docs/source/source_code/src/platform/macos/misc.rst b/docs/source/source_code/src/platform/macos/misc.rst
diff --git a/docs/source/source_code/src/platform/macos/nv12_zero_device.rst b/docs/source/source_code/src/platform/macos/nv12_zero_device.rst
diff --git a/docs/source/source_code/src/platform/windows/PolicyConfig.rst b/docs/source/source_code/src/platform/windows/PolicyConfig.rst
diff --git a/docs/source/source_code/src/platform/windows/display.rst b/docs/source/source_code/src/platform/windows/display.rst
diff --git a/docs/source/source_code/src/platform/windows/misc.rst b/docs/source/source_code/src/platform/windows/misc.rst
diff --git a/docs/source/source_code/src/process.rst b/docs/source/source_code/src/process.rst
diff --git a/docs/source/source_code/src/round_robin.rst b/docs/source/source_code/src/round_robin.rst
diff --git a/docs/source/source_code/src/rtsp.rst b/docs/source/source_code/src/rtsp.rst
diff --git a/docs/source/source_code/src/stream.rst b/docs/source/source_code/src/stream.rst
diff --git a/docs/source/source_code/src/sync.rst b/docs/source/source_code/src/sync.rst
diff --git a/docs/source/source_code/src/system_tray.rst b/docs/source/source_code/src/system_tray.rst
diff --git a/docs/source/source_code/src/task_pool.rst b/docs/source/source_code/src/task_pool.rst
diff --git a/docs/source/source_code/src/thread_pool.rst b/docs/source/source_code/src/thread_pool.rst
diff --git a/docs/source/source_code/src/thread_safe.rst b/docs/source/source_code/src/thread_safe.rst
diff --git a/docs/source/source_code/src/upnp.rst b/docs/source/source_code/src/upnp.rst
diff --git a/docs/source/source_code/src/utility.rst b/docs/source/source_code/src/utility.rst
diff --git a/docs/source/source_code/src/uuid.rst b/docs/source/source_code/src/uuid.rst
diff --git a/docs/source/source_code/src/video.rst b/docs/source/source_code/src/video.rst