docs: document code with doxygen, breathe, and sphinx_csharp

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "third-party/sphinx-csharp"]
+	path = third-party/sphinx-csharp
+	url = https://github.com/rogerbarton/sphinx-csharp.git
+	branch = master

.readthedocs.yaml

@@ -8,14 +8,21 @@ version: 2
 
 # Set the version of Python
 build:
-  os: ubuntu-20.04
+  os: ubuntu-22.04
   tools:
-    python: "3.10"
+    python: "3.11"
+  apt_packages:
+    - graphviz  # required to build diagrams
   jobs:
     post_build:
       - rstcheck -r .  # lint rst files
       # - rstfmt --check --diff -w 120 .  # check rst formatting
 
+# submodules required to install sphinx-csharp
+submodules:
+  include: all
+  recursive: true
+
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   builder: html

docs/requirements.txt

@@ -1,6 +1,10 @@
+breathe==4.35.0
 furo==2023.9.10
 m2r2==0.3.3.post2
 rstcheck[sphinx]==6.2.0
 rstfmt==0.0.14
 Sphinx==7.2.6
 sphinx-copybutton==0.5.2
+
+# install submodules
+./third-party/sphinx-csharp

docs/source/code/ThemerrManager.rst

@@ -0,0 +1,8 @@
+ThemerrManager
+==============
+
+.. doxygennamespace:: Jellyfin.Plugin.Themerr
+   :members:
+   :protected-members:
+   :private-members:
+   :undoc-members:

docs/source/conf.py

@@ -7,6 +7,7 @@
 # standard imports
 from datetime import datetime
 import os
+import subprocess
 
 
 # -- Path setup --------------------------------------------------------------
@@ -35,11 +36,13 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'breathe',  # c# support for sphinx with doxygen, and sphinx-csharp
     'm2r2',  # enable markdown files
     'sphinx.ext.autosectionlabel',
     'sphinx.ext.todo',  # enable to-do sections
     'sphinx.ext.viewcode',  # add links to view source code
     'sphinx_copybutton',  # add a copy button to code blocks
+    'sphinx_csharp',  # c# directives
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -83,4 +86,23 @@
 
 # extension config options
 autosectionlabel_prefix_document = True  # Make sure the target is unique
+breathe_default_project = 'Jellyfin.Plugin.Themerr'
+breathe_projects = {
+    "Jellyfin.Plugin.Themerr": "../build/doxyxml"
+}
+sphinx_csharp_test_links = True
 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)
+
+# 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))

docs/source/toc.rst

@@ -16,3 +16,9 @@
    contributing/database
    contributing/build
    contributing/testing
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Source Code
+
+   code/ThemerrManager