docs: use doxygen-awesome-css (#2758)

LizardByte · Jun 26, 2024 · 7e9a2dd · 7e9a2dd
1 parent cac1ca3
commit 7e9a2dd
Show file tree

Hide file tree

Showing 10 changed files with 166 additions and 9 deletions.
diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
@@ -992,7 +992,6 @@ jobs:
           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 \
-            doxygen \
             git \
             mingw-w64-ucrt-x86_64-boost \
             mingw-w64-ucrt-x86_64-cmake \
@@ -1007,6 +1006,31 @@ jobs:
             mingw-w64-ucrt-x86_64-opus \
             mingw-w64-ucrt-x86_64-toolchain
 
+      - name: Install Doxygen
+        # GCC compiled doxygen has issues when running graphviz
+        env:
+          DOXYGEN_VERSION: "1.11.0"
+        run: |
+          # Set version variables
+          $doxy_ver = $env:DOXYGEN_VERSION
+          $_doxy_ver = $doxy_ver.Replace(".", "_")
+
+          # Download the Doxygen installer
+          Invoke-WebRequest -Uri `
+            "https://github.com/doxygen/doxygen/releases/download/Release_${_doxy_ver}/doxygen-${doxy_ver}-setup.exe" `
+            -OutFile "doxygen-setup.exe"
+
+          # Run the installer
+          Start-Process `
+            -FilePath .\doxygen-setup.exe `
+            -ArgumentList `
+              '/VERYSILENT' `
+          -Wait `
+          -NoNewWindow
+
+          # Clean up
+          Remove-Item -Path doxygen-setup.exe
+
       - name: Setup python
         # use this instead of msys2 python due to known issues using wheels, https://www.msys2.org/docs/python/
         id: setup-python

diff --git a/.gitmodules b/.gitmodules
@@ -10,6 +10,10 @@
 	path = third-party/build-deps
 	url = https://github.com/LizardByte/build-deps.git
 	branch = dist
+[submodule "third-party/doxygen-awesome-css"]
+	path = third-party/doxygen-awesome-css
+	url = https://github.com/jothepro/doxygen-awesome-css.git
+	branch = main
 [submodule "third-party/googletest"]
 	path = third-party/googletest
 	url = https://github.com/google/googletest/

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -10,16 +10,20 @@ version: 2
 build:
   os: ubuntu-24.04
   tools:
-    python: "3.11"
+    python: "miniconda-latest"
   apt_packages:
-    - graphviz  # required to build diagrams
     - libboost-locale-dev  # required for rstcheck in cpp code block
   jobs:
     post_build:
       - find ./third-party -iname "*.rst" -type f -delete  # find and delete rst files in third-party
       - rstcheck -r .  # lint rst files
       # - rstfmt --check --diff -w 120 .  # check rst formatting
 
+# using conda, we can get newer doxygen and graphviz than ubuntu provide
+# https://github.com/readthedocs/readthedocs.org/issues/8151#issuecomment-890359661
+conda:
+  environment: docs/environment.yml
+
 # submodules required for include statements
 submodules:
   include: all

diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
@@ -39,6 +39,7 @@ unset(Python3_EXECUTABLE)
 
 set(VENV_PATTERNS
         ${VENV_DIR}/bin/python
+        ${VENV_DIR}/bin/python.exe
         ${VENV_DIR}/Scripts/python.exe
 )
 
@@ -119,7 +120,7 @@ list(APPEND SPHINX_BUILD_EPUB_COMMAND
 add_custom_target(docs ALL
         WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}"
         COMMENT "Building documentation"
-        COMMAND ${SPHINX_BUILD_HTML_COMMAND}
-        COMMAND ${SPHINX_BUILD_EPUB_COMMAND}
+        COMMAND ${CMAKE_COMMAND} -E env DOXY_PATH=$<TARGET_FILE:Doxygen::doxygen> ${SPHINX_BUILD_HTML_COMMAND}
+        COMMAND ${CMAKE_COMMAND} -E env DOXY_PATH=$<TARGET_FILE:Doxygen::doxygen> ${SPHINX_BUILD_EPUB_COMMAND}
         VERBATIM
 )
diff --git a/docs/Doxyfile b/docs/Doxyfile
@@ -28,6 +28,7 @@ DOXYFILE_ENCODING = UTF-8
 ALIASES = "rst=^^\verbatim embed:rst:leading-asterisk^^"
 ALIASES += "endrst=\endverbatim"
 
+DISABLE_INDEX = NO
 DOCBOOK_OUTPUT = doxydocbook
 DOCSET_BUNDLE_ID = dev.lizardbyte.Sunshine
 DOCSET_PUBLISHER_ID = dev.lizardbyte.Sunshine.documentation
@@ -37,15 +38,23 @@ DOT_IMAGE_FORMAT = svg
 # TODO: On Windows, Doxygen hangs when creating dot graphs if this is set to 0
 DOT_NUM_THREADS = 1
 
+FULL_SIDEBAR = NO
 GENERATE_HTML = YES
 GENERATE_LATEX = NO
+GENERATE_TREEVIEW = 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
 
 HAVE_DOT = YES
-HTML_COLORSTYLE = TOGGLE
+HTML_COLORSTYLE = LIGHT  # required with Doxygen >= 1.9.5
+HTML_EXTRA_FILES = ../third-party/doxygen-awesome-css/doxygen-awesome-darkmode-toggle.js
+HTML_EXTRA_FILES += ../third-party/doxygen-awesome-css/doxygen-awesome-fragment-copy-button.js
+HTML_EXTRA_FILES += ../third-party/doxygen-awesome-css/doxygen-awesome-paragraph-link.js
+HTML_EXTRA_FILES += ../third-party/doxygen-awesome-css/doxygen-awesome-interactive-toc.js
+HTML_EXTRA_STYLESHEET = ../third-party/doxygen-awesome-css/doxygen-awesome.css
+HTML_HEADER = doxygen/header.html
 HTML_OUTPUT = doxyhtml
 INCLUDE_PATH = ../third-party/build-deps/ffmpeg/Linux-x86_64/include/
 INPUT = ../src
@@ -55,7 +64,7 @@ MACRO_EXPANSION = YES
 MAN_OUTPUT = doxyman
 NUM_PROC_THREADS = 1
 PREDEFINED = DOXYGEN
-PROJECT_BRIEF = "Sunshine is a Gamestream host for Moonlight."
+PROJECT_BRIEF = "Self-hosted game stream host for Moonlight."
 PROJECT_ICON = ../sunshine.ico
 PROJECT_LOGO = ../sunshine.png
 PROJECT_NAME = Sunshine

diff --git a/docs/doxygen/header.html b/docs/doxygen/header.html
@@ -0,0 +1,95 @@
+<!-- HTML header for doxygen 1.10.0-->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="$langISO">
+<head>
+<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
+<meta http-equiv="X-UA-Compatible" content="IE=11"/>
+<meta name="generator" content="Doxygen $doxygenversion"/>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>
+<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
+<!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
+<!--PROJECT_ICON is not available with DOXYGEN < 1.10.0, so use the filename directly-->
+<link rel="icon" href="$relpath^sunshine.ico" type="image/x-icon" />
+<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
+<!--BEGIN DISABLE_INDEX-->
+  <!--BEGIN FULL_SIDEBAR-->
+<script type="text/javascript">var page_layout=1;</script>
+  <!--END FULL_SIDEBAR-->
+<!--END DISABLE_INDEX-->
+<script type="text/javascript" src="$relpath^jquery.js"></script>
+<script type="text/javascript" src="$relpath^dynsections.js"></script>
+$treeview
+$search
+$mathjax
+$darkmode
+<link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
+$extrastylesheet
+
+<!--DOXYGEN-AWESOME START-->
+<script type="text/javascript" src="$relpath^doxygen-awesome-darkmode-toggle.js"></script>
+<script type="text/javascript">
+  DoxygenAwesomeDarkModeToggle.init()
+</script>
+<script type="text/javascript" src="$relpath^doxygen-awesome-fragment-copy-button.js"></script>
+<script type="text/javascript">
+  DoxygenAwesomeFragmentCopyButton.init()
+</script>
+<script type="text/javascript" src="$relpath^doxygen-awesome-paragraph-link.js"></script>
+<script type="text/javascript">
+  DoxygenAwesomeParagraphLink.init()
+</script>
+<script type="text/javascript" src="$relpath^doxygen-awesome-interactive-toc.js"></script>
+<script type="text/javascript">
+  DoxygenAwesomeInteractiveToc.init()
+</script>
+<!--DOXYGEN-AWESOME END-->
+</head>
+<body>
+<!--BEGIN DISABLE_INDEX-->
+  <!--BEGIN FULL_SIDEBAR-->
+<div id="side-nav" class="ui-resizable side-nav-resizable"><!-- do not remove this div, it is closed by doxygen! -->
+  <!--END FULL_SIDEBAR-->
+<!--END DISABLE_INDEX-->
+
+<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
+
+<!--BEGIN TITLEAREA-->
+<div id="titlearea">
+<table cellspacing="0" cellpadding="0">
+ <tbody>
+ <tr id="projectrow">
+  <!--BEGIN PROJECT_LOGO-->
+  <td id="projectlogo"><img alt="Logo" src="$relpath^$projectlogo"$logosize/></td>
+  <!--END PROJECT_LOGO-->
+  <!--BEGIN PROJECT_NAME-->
+  <td id="projectalign">
+   <div id="projectname">$projectname<!--BEGIN PROJECT_NUMBER--><span id="projectnumber">&#160;$projectnumber</span><!--END PROJECT_NUMBER-->
+   </div>
+   <!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF-->
+  </td>
+  <!--END PROJECT_NAME-->
+  <!--BEGIN !PROJECT_NAME-->
+   <!--BEGIN PROJECT_BRIEF-->
+    <td>
+    <div id="projectbrief">$projectbrief</div>
+    </td>
+   <!--END PROJECT_BRIEF-->
+  <!--END !PROJECT_NAME-->
+  <!--BEGIN DISABLE_INDEX-->
+   <!--BEGIN SEARCHENGINE-->
+     <!--BEGIN !FULL_SIDEBAR-->
+    <td>$searchbox</td>
+     <!--END !FULL_SIDEBAR-->
+   <!--END SEARCHENGINE-->
+  <!--END DISABLE_INDEX-->
+ </tr>
+  <!--BEGIN SEARCHENGINE-->
+   <!--BEGIN FULL_SIDEBAR-->
+   <tr><td colspan="2">$searchbox</td></tr>
+   <!--END FULL_SIDEBAR-->
+  <!--END SEARCHENGINE-->
+ </tbody>
+</table>
+</div>
+<!--END TITLEAREA-->
+<!-- end header part -->
diff --git a/docs/environment.yml b/docs/environment.yml
@@ -0,0 +1,12 @@
+---
+name: RTD
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - doxygen=1.10.0
+  - graphviz=11.0.0
+  - pip
+  - python=3.11
+  - pip:
+      - -r ./requirements.txt
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -128,9 +128,12 @@ def _run_subprocess(
 # https://github.com/readthedocs/readthedocs.org/blob/eadf6ac6dc6abc760a91e1cb147cc3c5f37d1ea8/docs/conf.py#L235-L236
 suppress_warnings = ["epub.unknown_project_files"]
 
+doxygen_cmd = os.getenv('DOXY_PATH', 'doxygen')
+print(f'doxygen command: {doxygen_cmd}')
+
 # get doxygen version
 doxy_version = _run_subprocess(
-    args_list=['doxygen', '--version'],
+    args_list=[doxygen_cmd, '--version'],
     cwd=source_dir,
 )
 
@@ -147,7 +150,7 @@ def _run_subprocess(
 
 # run doxygen
 doxy_proc = _run_subprocess(
-    args_list=['doxygen', 'Doxyfile'],
+    args_list=[doxygen_cmd, 'Doxyfile'],
     cwd=source_dir
 )
 

diff --git a/docs/source/contributing/testing.rst b/docs/source/contributing/testing.rst
@@ -13,6 +13,10 @@ Test clang-format locally.
 
 Sphinx
 ------
+.. note:: Documentation is now a cmake target and this is all handled by the cmake build system. When compiling docs
+   as a target, simply install Python, Doxygen, and Graphviz. The installation of python dependencies will be handled
+   automatically inside a virtual environment. The following instructions are for manual building of the docs.
+
 Sunshine uses `Sphinx <https://www.sphinx-doc.org/en/master/>`__ for documentation building. Sphinx, along with other
 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.

diff --git a/third-party/doxygen-awesome-css b/third-party/doxygen-awesome-css