📚 GitHub pages to use mkdocs-material, add theme to doxygen

.github/workflows/documentation.yml

@@ -1,69 +1,80 @@
-# Workflow for building and deploying Etterna documentation
-name: Etterna documentation CI
+name: Docs CI
 
 on:
-  # Runs on pushes to develop
   push:
     branches: ["develop"]
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
 # Allow one concurrent deployment
 concurrency:
   group: "pages"
   cancel-in-progress: true
 
 jobs:
-  #Build job
-  build:
+  gen-documentation:
+    name: Generate Documentation
     runs-on: ubuntu-latest
+
     steps:
-      # Setup
-      - name: Checkout
+      - name: Checkout Etterna
         uses: actions/checkout@v3
-      - name: Update apt
-        run: "sudo apt-get update"
-      - name: Install Ldoc
-        run: "bash ./.ci/install_ldoc.sh"
-      - name: Generate LDoc/Doxygen configs
-        run: "bash ./.ci/generate_doc_configs.sh"
-      #Jekyll build
-      - name: Setup Pages
-        uses: actions/configure-pages@v2
-      - name: Build with Jekyll
-        uses: actions/jekyll-build-pages@v1
         with:
-          source: ./Docs/
-          destination: ./_site
-      #Ldoc build
-      - name: Run LDoc
+          path: main
+
+      - name: Install apt packages
+        run: sudo apt-get update && sudo apt-get install -y build-essential cmake ninja-build
+
+      - name: Install luver # Lua Version Manager
+        uses: MunifTanjim/luver-action@v1
+
+      - name: Install Lua and LuaRocks
         run: |
-          cd build
-          make ldoc
-          sudo mv ldoc_output ../_site/ldoc
-      #Doxygen build
-      - name: Run Doxygen
+          luver install lua 5.4.3
+          luver use 5.4.3
+          luver install luarocks 3.8.0
+
+      - name: Download doxygen binary and add to path
         run: |
-          cd build
-          make doxygen
-          sudo mv doxygen ../_site
-      - name: Upload artifact
+          curl -RO https://www.doxygen.nl/files/doxygen-1.9.6.linux.bin.tar.gz
+          tar -zxf doxygen-1.9.6.linux.bin.tar.gz
+          echo "$PWD/doxygen-1.9.6/bin" >> $GITHUB_PATH
+
+      - name: Install Python3
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+
+      - name: Install mkdocs
+        run: pip3 install mkdocs mkdocs-material
+
+      - name: Install LDoc
+        run: luarocks install ldoc
+
+      - name: Generate CMake
+        run: mkdir main/build && cd main/build && cmake -G Ninja -DDOCS_ONLY=1 ..
+
+      - name: Build documentation website
+        run: cmake --build main/build --target build-docs-website
+
+      - name: Upload docs_site to artifacts
         uses: actions/upload-pages-artifact@v1
+        with:
+          name: github-pages
+          path: main/build/docs_site
 
-  # Deployment job
   deploy:
+    name: Upload to Github Pages
+    runs-on: ubuntu-latest
+    needs: gen-documentation
+    permissions:
+      pages: write
+      id-token: write
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    needs: build
+
     steps:
       - name: Deploy to GitHub Pages
         id: deployment

CMake/Helpers/DocumentationTools.cmake

@@ -1,9 +1,21 @@
+include(FetchContent)
+
+set(DOCS_OUTPUT_DIR ${PROJECT_BINARY_DIR}/docs_site)
 
 # doxygen
 find_package(Doxygen OPTIONAL_COMPONENTS dot)
 if(NOT DOXYGEN_FOUND)
-    message(STATUS "Doxygen not found. Documentation target will not be created.")
+    message(STATUS "Doxygen not found. Doxygen target will not be created. Please ensure doxygen is accessibe within your path.")
 else()
+    # Download Doxygen Theme
+    FetchContent_Declare(doxygen_theme
+        GIT_REPOSITORY https://github.com/jothepro/doxygen-awesome-css.git
+        GIT_TAG	main
+        GIT_PROGRESS TRUE
+        GIT_SHALLOW TRUE)
+    FetchContent_MakeAvailable(doxygen_theme)
+    FetchContent_GetProperties(doxygen_theme SOURCE_DIR DOXY_THEME_DIR)
+
     # set input and output files
     set(DOXYGEN_IN ${PROJECT_SOURCE_DIR}/Docs/Doxyfile.in)
     set(DOXYGEN_OUT ${PROJECT_BINARY_DIR}/Doxyfile)
@@ -22,7 +34,7 @@ endif()
 # LDoc
 find_program(LDOC_EXE NAMES "ldoc" "ldoc.bat")
 if(NOT LDOC_EXE)
-    message(STATUS "LDoc not found. Documentation target will not be created.")
+    message(STATUS "LDoc not found. LDoc target will not be created. Please ensure ldoc is accessible within your path.")
 else()
     # set input and output files
     set(LDOC_IN ${PROJECT_SOURCE_DIR}/Docs/LDoc.in)
@@ -38,4 +50,31 @@ else()
         WORKING_DIRECTORY ${PROJECT_BINARY_DIR}
         COMMAND ${LDOC_EXE} .)
 
+endif()
+
+# mkdocs
+find_program(MKDOCS_EXE NAMES "mkdocs")
+if(NOT MKDOCS_EXE)
+    message(STATUS "mkdocs not found. Please ensure mkdocs is accessible within your path.")
+else()
+    # set input and output files
+    set(MKDOCS_IN ${PROJECT_SOURCE_DIR}/Docs/mkdocs.yml.in)
+    set(MKDOCS_OUT ${PROJECT_BINARY_DIR}/mkdocs.yml)
+
+    # configure the file
+    configure_file(${MKDOCS_IN} ${MKDOCS_OUT} @ONLY)
+
+    add_custom_target(mkdocs 
+        COMMENT "Generating mkdocs website"
+        VERBATIM
+        WORKING_DIRECTORY ${PROJECT_BINARY_DIR}
+        COMMAND ${MKDOCS_EXE} build --site-dir ${DOCS_OUTPUT_DIR}
+    )
+
+    add_custom_target(build-docs-website
+        WORKING_DIRECTORY ${PROJECT_BINARY_DIR}
+        COMMAND cmake --build ${PROJECT_BINARY_DIR} --target mkdocs
+        COMMAND cmake --build ${PROJECT_BINARY_DIR} --target doxygen
+        COMMAND cmake --build ${PROJECT_BINARY_DIR} --target ldoc
+    )
 endif()

CMakeLists.txt

@@ -32,11 +32,20 @@ set(CMAKE_EXPORT_COMPILE_COMMANDS ON)                           # Export compile
 set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_LIST_DIR}/CMake/Modules)  # Tell CMake where to access FindXXX.cmake files
 set_property(GLOBAL PROPERTY USE_FOLDERS ON)                    # Enable folders/filters within IDEs
 
-# Project Build Targets
-add_executable(Etterna)
-
 # Project Compile Options
 set(WITH_CRASHPAD TRUE CACHE BOOL "Compile with Crash Handler (Requires depot_tools installed)")
+set(DOCS_ONLY FALSE CACHE BOOL "Only prepare CMake for documentation. Do not prepare for game compilation.")
+
+## Documentation Preparation
+include(CMake/Helpers/DocumentationTools.cmake)
+
+## Do not continue processing if user only wants to build documentation.
+if(DOCS_ONLY)
+    return()
+endif()
+
+# Project Build Targets
+add_executable(Etterna)
 
 ## Setting Target Properties
 ### Set a different name for each output binary depending on what build configuration is.
@@ -141,9 +150,6 @@ endif()
 # Static Analysis
 include(CMake/Helpers/StaticAnalysis.cmake)
 
-# Documentation
-include(CMake/Helpers/DocumentationTools.cmake)
-
 # CPack Initialization
 include(CMake/Helpers/CPackSetup.cmake)
 include(CPack)

Docs/Doxyfile.in

@@ -5,13 +5,18 @@ DOXYFILE_ENCODING      = UTF-8
 PROJECT_NAME           = Etterna
 OUTPUT_LANGUAGE        = English
 PROJECT_NUMBER         = @PROJECT_VERSION@
-OUTPUT_DIRECTORY       = @PROJECT_BINARY_DIR@/doxygen
+OUTPUT_DIRECTORY       = @DOCS_OUTPUT_DIR@/doxygen
 INPUT                  = @PROJECT_SOURCE_DIR@/src
 INPUT_ENCODING         = UTF-8
 RECURSIVE              = YES
+EXCLUDE_PATTERNS       = */InputHandler/*.md
 
 # HTML
 GENERATE_HTML          = YES
+GENERATE_TREEVIEW      = YES
+HTML_TIMESTAMP         = YES
+HTML_DYNAMIC_MENUS     = YES
+HTML_DYNAMIC_SECTIONS  = YES
 HTML_OUTPUT            = html
 
 # DOT
@@ -21,3 +26,17 @@ DOT_NUM_THREADS        = 0
 
 # LATEX
 GENERATE_LATEX         = NO
+
+# THEME AWESOME DOXYGEN
+WARN_IF_UNDOCUMENTED   = NO
+GENERATE_TREEVIEW      = YES # required!
+DISABLE_INDEX          = NO
+FULL_SIDEBAR           = NO
+HTML_COLORSTYLE        = LIGHT
+PROJECT_LOGO           = @PROJECT_SOURCE_DIR@/Docs/docs/images/etterna-logo-light-transparent.svg
+HTML_HEADER            = @PROJECT_SOURCE_DIR@/Docs/style/doxygen/header.html
+HTML_EXTRA_FILES       = @DOXY_THEME_DIR@/doxygen-awesome-darkmode-toggle.js
+HTML_EXTRA_STYLESHEET  = @DOXY_THEME_DIR@/doxygen-awesome.css \
+                         @DOXY_THEME_DIR@/doxygen-awesome-sidebar-only.css \
+                         @DOXY_THEME_DIR@/doxygen-awesome-sidebar-only-darkmode-toggle.css \
+                         @PROJECT_SOURCE_DIR@/Docs/style/doxygen/style.css

Docs/LDoc.in

@@ -3,7 +3,7 @@ title = "Etterna Lua Documentation"
 description = "A cross-platform rhythm game"
 
 -- Output directory
-dir = "@PROJECT_BINARY_DIR@/ldoc_output"
+dir = "@DOCS_OUTPUT_DIR@/ldoc"
 
 -- Source files
 file = {"@PROJECT_SOURCE_DIR@/Themes/_fallback/Scripts/", "@PROJECT_SOURCE_DIR@/Themes/_fallback/docs/"}

Docs/docs/stylesheets/mkdocs.css

@@ -0,0 +1,9 @@
+:root {
+  --md-primary-fg-color:        #614080;
+  --md-primary-fg-color--light: #614080;
+  --md-primary-fg-color--dark:  #7950a1;
+}
+
+[data-md-color-scheme=slate] {
+  --md-default-bg-color:  #262626;
+}

Docs/mkdocs.yml.in

@@ -0,0 +1,52 @@
+# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json
+
+site_name: Etterna
+site_description: Advanced cross-platform rhythm game focused on keyboard play
+site_url: https://docs.etterna.dev
+repo_url: https://github.com/etternagame/etterna
+repo_name: Etterna
+docs_dir: @PROJECT_SOURCE_DIR@/Docs/docs
+
+extra_css:
+  - stylesheets/mkdocs.css
+
+theme:
+  name: material
+  favicon: @PROJECT_SOURCE_DIR@/Docs/docs/favicon.ico
+  font: false
+  features:
+    - navigation.tabs
+  icon:
+    repo: fontawesome/brands/github-alt
+  palette:
+    - scheme: default
+      toggle:
+        icon: material/brightness-5
+        name: Switch to dark mode
+    - scheme: slate
+      toggle:
+        icon: material/brightness-2
+        name: Switch to light mode
+
+extra:
+  # Hide "Made with Material" in footer
+  generator: false
+
+  # Bottom right footer icons
+  social:
+    - icon: simple/discord
+      link: https://discord.com/invite/etternaonline
+      name: Etterna Online
+    - icon: simple/discord
+      link: https://discord.gg/ZqpUjsJ
+      name: Etterna Dev Group
+
+nav:
+  - Welcome: 'README.md'
+  - Etterna Wiki: ''
+  - Developer Wiki:
+      - Building Etterna: 'Building.md'
+      - Crashpad: 'Crashpad.md'
+      - Bug Reporting: 'Bugreporting.md'
+  - Doxygen: 'doxygen/html/index.html'
+  - LDoc: 'ldoc/index.html'