refs #147: Code docblocks exporter (#156)

* refs #147: WIP on a custom docker image for GDQuest's gdscript-docs-maker.

* refs #147: wip on the dockerfile for reference generator.

* refs #147: A first version of the Code Reference generator is now working. Docs README explains how to use it.

* refs #147: GDScript codeblocks are now highlighted in documentation site. Added support for ancillary languages that may come in handy (md, bash, yaml, json, dockerfile, makefile).

* refs #147: Fixed typo in docs REAME.md file.

.gitignore

@@ -21,4 +21,12 @@ data_*/
 popochiu
 popochiu/**
 game
-game/**
+game/**
+
+# Documentation ignores
+docs/**/*.import
+docs/**/scripting-reference/*.md
+!docs/**/scripting-reference/index.md
+Collector*.gd
+ReferenceCollectorCLI*.gd
+reference.json

Dockerfile.DocsMaker

@@ -0,0 +1,46 @@
+FROM python:slim
+
+ARG GODOT_VERSION="4.1.3"
+ARG GODOT_RELEASE_NAME="stable"
+ARG GODOT_SUBDIR=""
+ARG GODOT_PLATFORM="linux.x86_64"
+
+ARG GDM_COMMIT_SHA="07cb0d8f0af6da745260d7bfabfc475504c413f1"
+
+# Override user name at build. If build-arg is not passed, will create user named `host_user`
+ARG DOCKER_USER=host_user
+ARG DOCKER_USER_UID=1000
+ARG DOCKER_USER_GID=1000
+
+
+RUN addgroup --system --gid ${DOCKER_USER_GID} ${DOCKER_USER} \
+    && adduser --system --uid ${DOCKER_USER_UID} --gid ${DOCKER_USER_GID} --home /home/${DOCKER_USER} ${DOCKER_USER} \
+    # Ensure proper permissions on user's home directory
+    && chown -R ${DOCKER_USER}:${DOCKER_USER} /home/${DOCKER_USER} \
+    # Install system-wide dependencies
+    && apt-get update && apt-get install -y --no-install-recommends unzip wget zip libfontconfig1 \
+    && rm -rf /var/lib/apt/lists/* \
+    # Install Godot from CDN
+    && wget -q https://downloads.tuxfamily.org/godotengine/${GODOT_VERSION}${GODOT_SUBDIR}/Godot_v${GODOT_VERSION}-${GODOT_RELEASE_NAME}_${GODOT_PLATFORM}.zip \
+    && mkdir /home/${DOCKER_USER}/.cache \
+    && mkdir -p /home/${DOCKER_USER}/.config/godot \
+    && mkdir -p /home/${DOCKER_USER}/.local/share/godot/export_templates/${GODOT_VERSION}.${GODOT_RELEASE_NAME} \
+    && unzip Godot_v${GODOT_VERSION}-${GODOT_RELEASE_NAME}_${GODOT_PLATFORM}.zip \
+    && mv Godot_v${GODOT_VERSION}-${GODOT_RELEASE_NAME}_${GODOT_PLATFORM} /usr/local/bin/godot \
+    && chmod a+x /usr/local/bin/godot \
+    && rm -f Godot_v${GODOT_VERSION}-${GODOT_RELEASE_NAME}_${GODOT_PLATFORM}.zip \
+    # Download gdscript-docs-maker source code
+    && wget https://github.com/GDQuest/gdscript-docs-maker/archive/${GDM_COMMIT_SHA}.zip -O gdscript-docs-maker.zip \
+    && unzip gdscript-docs-maker.zip \
+    && mv gdscript-docs-maker-${GDM_COMMIT_SHA} /app \
+    && rm -f gdscript-docs-maker.zip
+
+WORKDIR /app
+
+COPY --chmod=777 generate_reference generate_reference
+
+# Install application dependencies
+RUN python3 setup.py install
+
+# Run dockmaker script
+ENTRYPOINT ["./generate_reference"]

Makefile

@@ -1,12 +1,31 @@
+CURRENT_UID := $(shell id -u):$(shell id -g)
+
 all: up
 
-up:
+docs-up:
 	docker compose pull
 	docker compose up -d
 
-down:
+docs-down:
 	docker compose down
 
+gdm-build:
+	docker build \
+		--no-cache \
+		--build-arg="DOCKER_USER_UID=$(shell id -u)" \
+		--build-arg="DOCKER_USER_GID=$(shell id -g)" \
+		-t popochiu-docs-maker:latest \
+		-f Dockerfile.DocsMaker .
+
+gdm-generate:
+	docker run --rm \
+		-v .:/project \
+		-v ./docs/content/the-engine-handbook/scripting-reference:/output \
+		-u $(CURRENT_UID) \
+		popochiu-docs-maker:latest /project \
+		-o /output \
+		-d addons/popochiu/engine/
+
 cli:
 	docker compose run --rm documentation bash
 

docker-compose.yml

@@ -10,5 +10,5 @@ services:
             - com.dnsdock.alias=docs.popochiu.local
         build:
             context: .
-            dockerfile: Dockerfile
+            dockerfile: Dockerfile.MkDocs
         command: serve -a 0.0.0.0:80

docs/README.md

@@ -34,7 +34,7 @@ Please remember to install Docker as well as the Compose plugin.
 
 Make is provided by the `build-essential` metapackage on Ubuntu and derivatives, while on Arch and derivatives you can install `base-devel`:
 
-* **Ubuntu**: `sudo apt install build-essentials`
+* **Ubuntu**: `sudo apt install build-essential`
 * **Arch**: `sudo pacman -Sy base-devel`
 
 That's it. You can go to the "Run the docs" section to learn how to run your dock.
@@ -78,18 +78,38 @@ About Make, there are different ways to install it:
 
 To run the documentation, just enter the project's directory and issue this command:
 
-> `make local-docs-up'
+> `make docs-up'
 
 This will start the Docker container, and will bind port 286 of the host to the running instance of MkDocs in the container. To view the docs live in your browser, just visit [http://localhost:286](http://localhost:286).
 
 To stop the container service, just issue
 
-> `make local-docs-down`
+> `make docs-down`
 
 The documentation supports live reloading, so your browser will automatically update when you save a file you're working on, create a new file or folder.
 
 Please, read the contribution rules before pushing changes to Popochiu Documentation.
 
+## How to export scripting reference to the local development environment
+
+Scripting reference is automatically exported by GitHub Actions when the doc is published to production.  
+Should you want to export the refs locally to preview your work on the docs, a make command is available for that.
+
+**IMPORTANT:** a preliminary step to export the scripting reference is to build the necessary docker image. For that, issue:
+
+> `make gdm-build`
+
+and wait for the build to end successfully. Once it's done you can issue:
+
+> `make gdm-generate`
+
+to export all of the engine API docs to markdown format.  
+The exported refereces will be available in `The Engine Handbook > Scripting Reference` section of the documentation.
+
+**NOTE**: There is no live-reload of the source code. If you change the docblocks in the engine's source files, you will have to manually export local refs again.
+
+**NOTE**: Locally generated exports are ignored by Git.
+
 ## How to publish the documentation to production
 
 MkDocs is automatically triggered by GitHub automation so that new versions of the documentation are published whit every new release.

docs/content/_assets/css/custom.css

@@ -805,6 +805,10 @@ code,
     border: none;
     border-radius: 4px;
 }
+.rst-content pre code {
+    color: inherit;
+    background-color: var(--code-background-color);
+}
 
 .rst-content tt.literal,
 .rst-content code.literal {

docs/content/_assets/js/custom.js

@@ -302,6 +302,9 @@ $(document).ready(() => {
     }
   }
 
+  // Activate Highlight.js syntax-highlighter
+  hljs.highlightAll();
+
   // Change indentation from spaces to tabs for codeblocks.
   const codeBlocks = document.querySelectorAll('.rst-content div[class^="highlight"] pre');
   for (const codeBlock of codeBlocks) {

docs/content/the-engine-handbook/scripting-reference/index.md

@@ -2,4 +2,3 @@
 weight: 3020
 empty: true
 ---
-

docs/mkdocs.yml

@@ -1,7 +1,16 @@
 site_name: Popochiu
 extra_css:
   - _assets/css/custom.css
+  - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/tomorrow-night-bright.min.css
 extra_javascript:
+  - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js
+  - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/markdown.min.js
+  - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/bash.min.js
+  - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/yaml.min.js
+  - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/json.min.js
+  - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/dockerfile.min.js
+  - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/makefile.min.js
+  - _assets/js/gdscript.min.js
   - _assets/js/custom.js
 markdown_extensions:
   - admonition