refactor: use template to generate documentation

.codespellrc

@@ -1,3 +1,2 @@
 [codespell]
-skip = assets/**
-ignore-words-list = lod,LOD
+skip = addons/gd-plug/**,addons/gut/**

.env

@@ -2,7 +2,7 @@
 
 # Godot
 
-GODOT_VERSION=4.1.3
+GODOT_VERSION=4.2.1
 
 # Addon
 

.gitattributes

@@ -1,12 +1,18 @@
+# Properly detect languages on Github.
+*.gd linguist-language=GDScript
+
 # Normalize EOL for all files that Git considers text files.
 * text=auto eol=lf
-*.gd linguist-language=GDScript
+
+# The above only works properly for Git 2.10+, so for older versions
+# we need to manually list the binary files we don't want modified.
+*.mp3 binary
+*.png binary
 *.hdr binary
 
 # Exclude all top-level files and directories (except addons) from zip downloads.
 # This makes installing through the AssetLib easier, because no files and folders
 # need to be unchecked.
-
-/**				export-ignore
-/addons/godot-gherkin		!export-ignore
-/addons/godot-gherkin/**	!export-ignore
+/**				                    export-ignore
+/addons/godot-autogen-docs			!export-ignore
+/addons/godot-autogen-docs/**		!export-ignore

.github/workflows/release-packaging.yml

@@ -19,8 +19,13 @@ jobs:
       - name: Load dotenv
         run: just ci-load-dotenv
 
+      # Retry multiple times, sometimes in CI, gdlint raise "file exists"
       - name: Check
-        run: just fmt
+        uses: nick-fields/retry@v2
+        with:
+          timeout_minutes: 1
+          max_attempts: 3
+          command: just fmt
 
       - name: Ensure version is equal to tag
         if: startsWith(github.ref, 'refs/tags/')
@@ -31,8 +36,10 @@ jobs:
     runs-on: ubuntu-22.04
     timeout-minutes: 30
 
-    matrix:
-      - godot_version: ['4.0.4', '4.1.3']
+    strategy:
+      fail-fast: true
+      matrix:
+        godot_version: ['4.1.3', '4.2.1']
 
     steps:
       - uses: actions/checkout@v4
@@ -42,8 +49,8 @@ jobs:
         with:
           python-version: '3.10'
 
-      - name: Check
-        run: just doc
+      - name: Test
+        run: just test
         env:
           GODOT_VERSION: ${{ matrix.godot_version }}
 

.gitignore

@@ -10,14 +10,15 @@ gfxrecon_capture_*
 .mono/
 data_*/
 
+# gd-plug
+.plugged/
+addons/*
+!addons/gd-plug/
+!addons/godot-autogen-docs/
+
 # Python-specific ignores
 venv/
 
-# Export output
-dist/
-build/
-override.cfg
-
 # Docs output
 reference.json
 site/

.gutconfig.json

@@ -0,0 +1,10 @@
+{
+  "dirs": [
+    "res://test/"
+  ],
+  "prefix": "",
+  "suffix": ".test.gd",
+  "include_subdirs": true,
+  "log_level": 1,
+  "should_exit": true
+}

.pre-commit-config.yaml

@@ -46,6 +46,11 @@ repos:
     entry: gdformat
     language: system
     files: \.gd$
+    exclude: |
+      (?x)^(
+          addons/gd-plug/|
+          plug.gd
+      )
   - id: check-shaders
     name: check shaders
     entry: clang-format
@@ -55,9 +60,13 @@ repos:
       - -i
     language: system
     files: \.gdshader$
-    exclude: ^addons/
   - id: lint-gdscript
     name: lint gdscript
     entry: gdlint
     language: system
     files: \.gd$
+    exclude: |
+      (?x)^(
+          addons/gd-plug/|
+          plug.gd
+      )

.reuse/dep5

@@ -7,3 +7,14 @@ Files: *
 Copyright: 2022-present Florian Vazelle
 License: MIT
 
+# Addons
+
+Files: addons/gd-plug/*
+Copyright: 2021 Tan Jian Ping
+License: MIT
+Source: https://github.com/imjp94/gd-plug
+
+Files: addons/gut/*
+Copyright: 2018 Tom "Butch" Wesley
+License: MIT
+Source: https://github.com/bitwes/Gut

CHANGELOG.md

@@ -9,5 +9,3 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 ### Fixed
 ### Security
 ### Dependencies
-
-- Bump `actions/setup-python` from 4 to 5 ([#2](https://github.com/MechanicalFlower/godot-autogen-docs/pull/2))

Justfile

@@ -67,10 +67,17 @@ install-godot:
 install-addons:
     [ -f plug.gd ] && just godot --headless --script plug.gd install || true
 
+# Workaround from https://github.com/godotengine/godot/pull/68461
+# Import game resources
+import-resources:
+    just godot --headless --export-pack null /dev/null
+    # timeout 60 just godot --editor || true
+    # just godot --headless --quit --editor
+
 # Updates the addon version
 @bump-version:
-    echo "Update version in the plugin.cfg"
-    sed -i "s,version=.*$,version=\"{{ addon_version }}\",g" ./addons/{{ addon_name }}/plugin.cfg
+    # echo "Update version in the plugin.cfg"
+    # sed -i "s,version=.*$,version=\"{{ addon_version }}\",g" ./addons/{{ addon_name }}/plugin.cfg
 
 # Godot binary wrapper
 @godot *ARGS: makedirs install-godot
@@ -110,12 +117,19 @@ publish:
     gh release create "{{ addon_version }}" --title="v{{ addon_version }}" --generate-notes
     # TODO: Add a asset-lib publish step
 
+cli *ARGS:
+    just godot --editor --headless --quit --script addons/godot-autogen-docs/cli.gd {{ ARGS }}
+
+# Generate documentation
 doc:
-    just godot --editor --headless --quit --script addons/godot-autogen-docs/reference_collector_cli.gd
-    just godot --headless --quit --script addons/godot-autogen-docs/markdown.gd
+    just godot --editor --headless --quit --script addons/godot-autogen-docs/cli.gd readthedocs -ddir=res://addons/godot-autogen-docs -doutdir=res://docs/dev-guide/api-ref/
     just venv pip install mkdocs==1.5.3 mkdocs-literate-nav==0.6.1
     just venv mkdocs build
 
-serve:
-    just venv pip install mkdocs==1.5.3 mkdocs-literate-nav==0.6.1
+# Start serving the documentation
+serve: doc
     just venv mkdocs serve
+
+# Run unit tests
+test: install-addons import-resources
+    just godot --headless --script addons/gut/gut_cmdln.gd -gconfig=.gutconfig.json

README.md

@@ -3,7 +3,7 @@
 
 # Godot Autogen Docs
 
-![Godot Badge](https://img.shields.io/badge/godot-4.0|4.1-blue?logo=Godot-Engine&logoColor=white)
+![Godot Badge](https://img.shields.io/badge/godot-4.1%20%7C%204.2-blue?logo=Godot-Engine&logoColor=white)
 ![license](https://img.shields.io/badge/license-MIT-green?logo=open-source-initiative&logoColor=white)
 ![reuse](./.reuse/REUSE-compliant.svg)
 
@@ -16,14 +16,20 @@ Godot addon that automatically turns your code
 
 ### Usage
 
-To generate a `reference.json`, run:
-```
-godot --editor --headless --quit --script addons/godot-autogen-docs/reference_collector_cli.gd
 ```
+$ just godot --editor --headless --quit --script addons/godot-autogen-docs/cli.gd help
 
-And to turn this JSON file into markdown, run:
-```
-godot --headless --quit --script addons/godot-autogen-docs/markdown.gd
+Usage:
+        godot --editor --headless --quit --script res://addons/godot-autogen-docs/cli.gd <command> [<options> ...]
+
+Commands:
+        help                    Display this text
+        markdown                Export documentation to markdown
+        readthedocs             Export documentation to markdown compatible with the readthedocs theme
+
+Options:
+        -ddir                   Comma delimited list of directories to collect files from
+        -doutdir                A directory for saving documentation files
 ```
 
 ## Contributing