From 7e9a2dd621d803a58d460e698e897c3602bf07e2 Mon Sep 17 00:00:00 2001 From: ReenigneArcher <42013603+ReenigneArcher@users.noreply.github.com> Date: Wed, 26 Jun 2024 10:44:32 -0400 Subject: [PATCH] docs: use doxygen-awesome-css (#2758) --- .github/workflows/CI.yml | 26 +++++++- .gitmodules | 4 ++ .readthedocs.yaml | 8 ++- docs/CMakeLists.txt | 5 +- docs/Doxyfile | 13 +++- docs/doxygen/header.html | 95 ++++++++++++++++++++++++++++ docs/environment.yml | 12 ++++ docs/source/conf.py | 7 +- docs/source/contributing/testing.rst | 4 ++ third-party/doxygen-awesome-css | 1 + 10 files changed, 166 insertions(+), 9 deletions(-) create mode 100644 docs/doxygen/header.html create mode 100644 docs/environment.yml create mode 160000 third-party/doxygen-awesome-css diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index dd0224f4..6b0fa2d6 100644 --- 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 index 15f85046..cdcb39f7 100644 --- 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 index 4eb6ef0b..aa2f75f8 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -10,9 +10,8 @@ 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: @@ -20,6 +19,11 @@ build: - 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 index 373e4118..31d0f48c 100644 --- 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=$ ${SPHINX_BUILD_HTML_COMMAND} + COMMAND ${CMAKE_COMMAND} -E env DOXY_PATH=$ ${SPHINX_BUILD_EPUB_COMMAND} VERBATIM ) diff --git a/docs/Doxyfile b/docs/Doxyfile index 9e83aba8..281b8429 100644 --- 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 new file mode 100644 index 00000000..1f8d0d05 --- /dev/null +++ b/docs/doxygen/header.html @@ -0,0 +1,95 @@ + + + + + + + + +$projectname: $title +$title + + + + + + + + + + +$treeview +$search +$mathjax +$darkmode + +$extrastylesheet + + + + + + + + + + + + + + + +
+ + + +
+ + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
$projectname $projectnumber +
+
$projectbrief
+ 		+
$projectbrief
+ 		$searchbox
$searchbox
+
+ + diff --git a/docs/environment.yml b/docs/environment.yml new file mode 100644 index 00000000..5919549d --- /dev/null +++ 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 index 04c40ce8..eb3845e6 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -128,9 +128,12 @@ todo_include_todos = True # 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 @@ for d in directories: # 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 index 2d9f6290..c1360a09 100644 --- 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 `__ 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 new file mode 160000 index 00000000..40e9b25b --- /dev/null +++ b/third-party/doxygen-awesome-css @@ -0,0 +1 @@ +Subproject commit 40e9b25b6174dd3b472d8868f63323a870dfeeb8