docs: add doxygen (#1004)

docs/requirements.txt

@@ -1,3 +1,4 @@
+breathe==4.35.0
 furo==2022.12.7
 m2r2==0.3.3.post2
 Sphinx==6.1.3

docs/source/about/changelog.rst

@@ -0,0 +1 @@
+.. mdinclude:: ../../../CHANGELOG.md

docs/source/about/docker.rst

@@ -1,3 +1 @@
-:github_url: https://github.com/LizardByte/Sunshine/tree/nightly/docs/DOCKER_README.md
-
 .. mdinclude:: ../../../DOCKER_README.md

docs/source/conf.py

@@ -8,6 +8,7 @@
 from datetime import datetime
 import os
 import re
+import subprocess
 
 
 # -- Path setup --------------------------------------------------------------
@@ -43,9 +44,11 @@ To use cmake method for obtaining version instead of regex,
 # 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
 ]
@@ -82,4 +85,12 @@ 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
+
+subprocess.run('doxygen', shell=True, cwd=source_dir)

docs/source/contributing/testing.rst

@@ -14,11 +14,16 @@ Test clang-format locally.
 Sphinx
 ------
 Sunshine uses `Sphinx <https://www.sphinx-doc.org/en/master/>`_ for documentation building. Sphinx, along with other
-required documentation depencies are included in the `./docs/requirements.txt` file. Python is required to build
+required python dependencies are included in the `./docs/requirements.txt` file. Python is required to build
 sphinx docs. Installation and setup of python will not be covered here.
 
+Doxygen is used to generate the XML files required by Sphinx. Doxygen can be obtained from
+`Doxygen downloads <https://www.doxygen.nl/download.html>`_. Ensure that the `doxygen` executable is in your path.
+
 The config file for Sphinx is `docs/source/conf.py`. This is already included in the repo and should not be modified.
 
+The config file for Doxygen is `docs/Doxyfile`. This is already included in the repo and should not be modified.
+
 Test with Sphinx
    .. code-block:: bash
 

docs/source/index.rst

@@ -1,5 +1,3 @@
-:github_url: https://github.com/LizardByte/Sunshine/tree/nightly/docs/source/index.rst
-
 Table of Contents
 =================
 .. include:: toc.rst

docs/source/source/src.rst

@@ -0,0 +1,85 @@
+src
+===
+We are in process of improving the source code documentation. Code should be documented using Doxygen syntax.
+Some examples exist in `main.h` and `main.cpp`. In order for documentation within the code to appear in the
+rendered docs, the definition of the object must be in a header file, although the documentation itself can (and
+should) be in the source file.
+
+Example Documentation Blocks
+----------------------------
+
+**file.h**
+
+.. code-block:: cpp
+
+   // functions
+   int main(int argc, char *argv[]);
+
+**file.cpp** (with markdown)
+
+.. code-block:: cpp
+
+   /**
+    * @brief Main application entry point.
+    * @param argc The number of arguments.
+    * @param argv The arguments.
+    *
+    * EXAMPLES:
+    * ```cpp
+    * main(1, const char* args[] = {"hello", "markdown", nullptr});
+    * ```
+    */
+   int main(int argc, char *argv[]) {
+     // do stuff
+   }
+
+**file.cpp** (with ReStructuredText)
+
+.. code-block:: cpp
+
+   /**
+    * @brief Main application entry point.
+    * @param argc The number of arguments.
+    * @param argv The arguments.
+    * @rst
+    * EXAMPLES:
+    *
+    * .. code-block:: cpp
+    *    main(1, const char* args[] = {"hello", "rst", nullptr});
+    * @endrst
+    */
+   int main(int argc, char *argv[]) {
+     // do stuff
+   }
+
+Code
+----
+
+.. toctree::
+   :maxdepth: 2
+   :caption: src
+
+   src/main
+   src/audio
+   src/cbs
+   src/config
+   src/confighttp
+   src/crypto
+   src/httpcommon
+   src/input
+   src/move_by_copy
+   src/network
+   src/nvhttp
+   src/process
+   src/round_robin
+   src/rtsp
+   src/stream
+   src/sync
+   src/task_pool
+   src/thread_pool
+   src/thread_safe
+   src/upnp
+   src/utility
+   src/uuid
+   src/video
+   src/platform

docs/source/source/src/audio.rst

@@ -0,0 +1,4 @@
+audio
+=====
+
+.. doxygenfile:: audio.h

docs/source/source/src/cbs.rst

@@ -0,0 +1,4 @@
+cbs
+===
+
+.. doxygenfile:: cbs.h

docs/source/source/src/config.rst

@@ -0,0 +1,4 @@
+config
+======
+
+.. doxygenfile:: config.h

docs/source/source/src/confighttp.rst

@@ -0,0 +1,4 @@
+confighttp
+==========
+
+.. doxygenfile:: confighttp.h

docs/source/source/src/crypto.rst

@@ -0,0 +1,4 @@
+crypto
+======
+
+.. doxygenfile:: crypto.h

docs/source/source/src/httpcommon.rst

@@ -0,0 +1,4 @@
+httpcommon
+==========
+
+.. doxygenfile:: httpcommon.h

docs/source/source/src/input.rst

@@ -0,0 +1,4 @@
+input
+=====
+
+.. doxygenfile:: input.h

docs/source/source/src/main.rst

@@ -0,0 +1,4 @@
+main
+====
+
+.. doxygenfile:: main.h

docs/source/source/src/move_by_copy.rst

@@ -0,0 +1,4 @@
+move_by_copy
+============
+
+.. doxygenfile:: move_by_copy.h

docs/source/source/src/network.rst

@@ -0,0 +1,4 @@
+network
+=======
+
+.. doxygenfile:: network.h

docs/source/source/src/nvhttp.rst

@@ -0,0 +1,4 @@
+nvhttp
+======
+
+.. doxygenfile:: nvhttp.h

docs/source/source/src/platform.rst

@@ -0,0 +1,10 @@
+platform
+========
+
+.. toctree::
+   :maxdepth: 1
+
+   platform/common
+   platform/linux
+   platform/macos
+   platform/windows

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

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

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

@@ -0,0 +1,12 @@
+linux
+=====
+
+.. toctree::
+   :maxdepth: 1
+
+   linux/cuda
+   linux/graphics
+   linux/misc
+   linux/vaapi
+   linux/wayland
+   linux/x11grab

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

@@ -0,0 +1,4 @@
+cuda
+====
+
+.. Todo:: Add cuda.h

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

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

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

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

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

@@ -0,0 +1,4 @@
+vaapi
+=====
+
+.. Todo:: Add vaapi.h

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

@@ -0,0 +1,4 @@
+wayland
+=======
+
+.. Todo:: Add wayland.h

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

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

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

@@ -0,0 +1,11 @@
+macos
+=====
+
+.. toctree::
+   :maxdepth: 1
+
+   macos/av_audio
+   macos/av_img_t
+   macos/av_video
+   macos/misc
+   macos/nv12_zero_device

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,9 @@
+windows
+=======
+
+.. toctree::
+   :maxdepth: 1
+
+   windows/display
+   windows/misc
+   windows/PolicyConfig

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

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

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

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

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

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

docs/source/source/src/process.rst

@@ -0,0 +1,4 @@
+process
+=======
+
+.. doxygenfile:: process.h

docs/source/source/src/round_robin.rst

@@ -0,0 +1,4 @@
+round_robin
+===========
+
+.. doxygenfile:: round_robin.h

docs/source/source/src/rtsp.rst

@@ -0,0 +1,4 @@
+rtsp
+====
+
+.. doxygenfile:: rtsp.h

docs/source/source/src/stream.rst

@@ -0,0 +1,4 @@
+stream
+======
+
+.. doxygenfile:: stream.h

docs/source/source/src/sync.rst

@@ -0,0 +1,4 @@
+sync
+====
+
+.. doxygenfile:: sync.h

docs/source/source/src/task_pool.rst

@@ -0,0 +1,4 @@
+tasl_pool
+=========
+
+.. doxygenfile:: task_pool.h

docs/source/source/src/thread_pool.rst

@@ -0,0 +1,4 @@
+thread_pool
+===========
+
+.. doxygenfile:: thread_pool.h

docs/source/source/src/thread_safe.rst

@@ -0,0 +1,4 @@
+thread_safe
+===========
+
+.. doxygenfile:: thread_safe.h

docs/source/source/src/upnp.rst

@@ -0,0 +1,4 @@
+upnp
+====
+
+.. doxygenfile:: upnp.h

docs/source/source/src/utility.rst

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

docs/source/source/src/uuid.rst

@@ -0,0 +1,4 @@
+uuid
+====
+
+.. doxygenfile:: uuid.h

docs/source/source/src/video.rst

@@ -0,0 +1,4 @@
+video
+=====
+
+.. doxygenfile:: video.h

docs/source/toc.rst

@@ -9,6 +9,7 @@
    about/usage
    about/app_examples
    about/advanced_usage
+   about/changelog
 
 .. toctree::
    :maxdepth: 2
@@ -47,3 +48,9 @@
    :caption: Legal
 
    legal/legal
+
+.. toctree::
+   :maxdepth: 2
+   :caption: source
+
+   source/src