chore(Docs): migrate to mkdocs

.github/workflows/docs.yaml

@@ -0,0 +1,28 @@
+name: "📄 Documentation"
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: ~/.cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material mkdocs-awesome-nav
+      - run: mkdocs gh-deploy --force

.github/workflows/test.yaml

@@ -14,4 +14,4 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - run: |
-          make in-docker IMAGE_TAG=4.4.1 TARGET='import test GAMESCOPE_CMD='
+          make in-docker IMAGE_TAG=4.5.1 TARGET='import docs dist test GAMESCOPE_CMD='

.gitignore

@@ -8,3 +8,4 @@ settings.mk
 RyzenAdj
 .gut_editor_config.json
 result
+target

.readthedocs.yaml

@@ -0,0 +1,18 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3"
+  jobs:
+    pre_install:
+      - pip install mkdocs-material mkdocs-awesome-nav
+
+mkdocs:
+  configuration: mkdocs.yml

.releaserc.yaml

@@ -35,7 +35,7 @@ plugins:
   # Execute commands to build the project
   - - "@semantic-release/exec"
     - shell: true
-      prepareCmd: "make in-docker IMAGE_TAG=4.5.1 TARGET='force-import dist update-pkgbuild-hash'"
+      prepareCmd: "make in-docker IMAGE_TAG=4.5.1 TARGET='force-import docs dist update-pkgbuild-hash'"
       publishCmd: "echo '${nextRelease.version}' > .version.txt"
 
   # Commit the following changes to git after other plugins have run
@@ -44,6 +44,8 @@ plugins:
         - core/global/version.tres
         - package/rpm/opengamepadui.spec
         - package/archlinux/PKGBUILD
+        - docs/class-reference/.nav.yml
+        - docs/class-reference/*.md
 
   # Publish artifacts as a GitHub release
   - - "@semantic-release/github"

Makefile

@@ -207,25 +207,38 @@ debug-overlay: $(IMPORT_DIR) ## Run the project in debug mode in gamescope with
 		--position 320,140 res://entrypoint.tscn --overlay-mode -- steam -gamepadui -steamos3 -steampal -steamdeck
 
 .PHONY: docs
-docs: docs/api/classes/.generated ## Generate docs
+docs: docs/api/classes/.generated ## Generate class reference docs
 docs/api/classes/.generated: $(IMPORT_DIR) $(ALL_GDSCRIPT)
-	rm -rf docs/api/classes
-	mkdir -p docs/api/classes
+	rm -rf $(CACHE_DIR)/docs/api/classes
+	mkdir -p $(CACHE_DIR)/docs/api/classes
+	@echo "Generating GDExtension class references"
 	$(GODOT) \
 		--editor \
 		--quit \
-		--doctool docs/api/classes \
+		--doctool $(CACHE_DIR)/docs/api/classes \
 		--no-docbase \
 		--gdextension-docs
+	mv $(CACHE_DIR)/docs/api/classes/doc_classes/*.xml $(CACHE_DIR)/docs/api/classes
+	rmdir $(CACHE_DIR)/docs/api/classes/doc_classes
+	@echo "Generating GDScript class references"
 	$(GODOT) \
 		--editor \
 		--path $(PWD) \
 		--quit \
-		--doctool docs/api/classes \
+		--doctool $(CACHE_DIR)/docs/api/classes \
 		--no-docbase \
-		--gdscript-docs core
-	rm -rf docs/api/classes/core--*
-	$(MAKE) -C docs/api rst
+		--gdscript-docs .
+	@echo "Removing non-class documentation"
+	rm $(CACHE_DIR)/docs/api/classes/entrypoint.gd.xml
+	rm -rf $(CACHE_DIR)/docs/api/classes/core--*
+	rm -rf $(CACHE_DIR)/docs/api/classes/addons--*
+	rm -rf $(CACHE_DIR)/docs/api/classes/plugins--*
+	$(MAKE) docgen
+
+docgen:
+	rm -f ./docs/class-reference/*.md
+	cd ./extensions && \
+		cargo run --bin docgen -- ../$(CACHE_DIR)/docs/api/classes ../docs/class-reference
 
 .PHONY: inspect
 inspect: $(IMPORT_DIR) ## Launch Gamescope inspector

README.md

@@ -11,11 +11,11 @@
   <a href="https://discord.gg/Ea9ABXhtkv"><img alt="Discord" src="https://img.shields.io/discord/721211671124770837?label=discord" /></a>
   <br>
   <br>
-  <img src="https://raw.githubusercontent.com/ShadowBlip/OpenGamepadUI/main/docs/media/screenshot01.png" alt="OpenGamepadUI screenshot" width="80%">
+  <img src="https://raw.githubusercontent.com/ShadowBlip/OpenGamepadUI/main/docs/assets/screenshot01.png" alt="OpenGamepadUI screenshot" width="80%">
   <p align="center" width="100%">
-    <img src="https://raw.githubusercontent.com/ShadowBlip/OpenGamepadUI/main/docs/media/screenshot02.png" alt="OpenGamepadUI screenshot" width="30%">
-    <img src="https://raw.githubusercontent.com/ShadowBlip/OpenGamepadUI/main/docs/media/screenshot03.png" alt="OpenGamepadUI screenshot" width="30%">
-    <img src="https://raw.githubusercontent.com/ShadowBlip/OpenGamepadUI/main/docs/media/screenshot04.png" alt="OpenGamepadUI screenshot" width="30%">
+    <img src="https://raw.githubusercontent.com/ShadowBlip/OpenGamepadUI/main/docs/assets/screenshot02.png" alt="OpenGamepadUI screenshot" width="30%">
+    <img src="https://raw.githubusercontent.com/ShadowBlip/OpenGamepadUI/main/docs/assets/screenshot03.png" alt="OpenGamepadUI screenshot" width="30%">
+    <img src="https://raw.githubusercontent.com/ShadowBlip/OpenGamepadUI/main/docs/assets/screenshot04.png" alt="OpenGamepadUI screenshot" width="30%">
   </p>
 </p>
 

docs/.nav.yml

@@ -0,0 +1,4 @@
+nav:
+  - Home: ./index.md
+  - ./documentation
+  - ./class-reference