GDScript Docs Maker is a set of tools to convert documentation you write inside your code to an online or offline code reference in the markdown or hugo format. If you make plugins or a framework for Godot, GDScript Docs Maker will generate API reference documentation from your code.
It creates documents following Godot's built-in class reference. You can see an example with our Godot Steering Toolkit documentation
GDScript Docs Maker can be either used using the official Docker image or by installing it locally. For the docker image, only Docker is required.
For the local installation, Godot 3.2+ and Python 3.7+ are required.
To generate your API documentation, you mount the path of your game and the path of the output into the container and run it like this:
docker run --rm -v /my/game:/game -v /my/game/docs/api:/output gdquest/gdscript-docs-maker:latest /game -o /output
This will generate the API documentation in the subpath docs/api of your game located at /my/game. See below for further parameters.
You can install the GDScript Docs Maker python package with pip:
# On Linux and MacOS:
python3 -m pip install gdscript_docs_maker
# On Windows, if you installed Python 3.7+, you can use:
python -m pip install gdscript_docs_makerAlthough to use the shell script that simplifies creating the reference, generate_reference, you need to clone this repository. More on that below.
Docstring or doc-comments in GDScript don't have any special markup.
You can document classes, properties, and functions with comment blocks placed on the line before their definition.
Example of docstrings for Godot 3:
# A linear and angular amount of acceleration.
class_name GSTTargetAcceleration
# Linear acceleration
var linear: = Vector3.ZERO
# Angular acceleration
var angular: = 0.0
# Resets the accelerations to zero
func reset() -> void:
linear = Vector3.ZERO
angular = 0.0Example of docstrings for Godot 4:
## A linear and angular amount of acceleration.
class_name GSTTargetAcceleration
## Linear acceleration
var linear: = Vector3.ZERO
## Angular acceleration
var angular: = 0.0
## Resets the accelerations to zero
func reset() -> void:
linear = Vector3.ZERO
angular = 0.0If you need long docstrings, you can use multiple commented lines:
## A specialized steering agent that updates itself every frame so the user does
## not have to using a KinematicBody2D
## category: Specialized agents
extends GSAISpecializedAgent
class_name GSAIKinematicBody2DAgentWe wrote two shell scripts to automate the steps in generating a code reference: ./generate_reference for Linux or MacOS, and ./generate_reference.bat for Windows.
Use either of them to quickly generate your code reference:
Generate a code reference from GDScript
Usage:
generate_reference $project_directory [options]
Required arguments:
$project_directory -- path to your Godot project directory.
This directory or one of its subdirectories should contain a
project.godot file.
Options:
-h/--help -- Display this help message.
-o/--output-directory -- directory path to output the documentation into.
-d/--directory -- Name of a directory to find files and generate the code reference in the Godot project.
You can use the option multiple times to generate a reference for multiple directories.
-f/--format -- Either `markdown` or `hugo`. If `hugo`, the output document includes a TOML front-matter
at the top. Default: `markdown`.
-a/--author -- If --format is `hugo`, controls the author property in the TOML front-matter.
Usage example:
generate_reference ~/Repositories/other/nakama-godot/project/ -o export-nakama -d addons
This command walks files in the res://addons directory of the Godot Nakama project, and converts it
to markdown files output in ./export-nakama.To use them:
- You need to clone this repository or download the source code from a stable release.
- You need
godotto be available on the system PATH variable.
You can output markdown files for hugo, the static website engine.
To do so, call GDScript docs maker with the --format hugo option. You can use two extra flags with this:
--date YYYY-MM-DD, the date in iso format, if you want the documents to have a date other than today. Default: datetime.date.today()
--author author_id, the id of the author on your hugo website, to assign an the author for the documents. Default: ""Here's how I generate the Godot Steering Toolkit's documentation. This command outputs the class reference straight into the website:
python3 -m gdscript_docs_maker $HOME/Repositories/godot-steering-toolkit/project/reference.json --format hugo --author razoric --path $HOME/Repositories/website/content/docs/godot-steering-toolkit/reference/classes/If you want to generate the JSON and convert it manually, there are three steps involved:
- Copying the GDScript files to your Godot project:
./godot-scripts/Collector.gdand./godot-scripts/ReferenceCollectorCLI.gdor./godot-scripts/ReferenceCollectorCLI.gdfor Godot 3./godot-scripts/CollectorGd4.gdand./godot-scripts/ReferenceCollectorCLIGd4.gdor./godot-scripts/ReferenceCollectorCLIGd4.gdfor Godot 4
- Running the GDScript code with Godot, either from the editor (
ReferenceCollector.gd/ReferenceCollectorGd4.gd) or by calling Godot from the command line (ReferenceCollectorCLI.gd/ReferenceCollectorCLIGd4.gd). - Running
gdscript_docs_makeron the reference.json file that Godot generated in the previous step.
Note: to parse and collect data from GDScript code, we rely on the GDScript language server that's new in Godot 3.2.
Call the gdscript-docs-maker package directly using the python -m option:
Usage: gdscript_docs_maker [-h] [-p PATH] [-v] [--dry-run] files [files ...]
Merges or converts json data dumped by Godot's GDScript language server to
create a code reference.
positional arguments:
files A list of paths to JSON files.
optional arguments:
-h, --help Show this help message and exit.
-p PATH, --path PATH Path to the output directory.
-v, --verbose Set the verbosity level. For example, -vv sets the
verbosity level to 2. Default: 0.
--dry-run Run the script without creating
files and folders. For debugging purposes.
The program takes a list of JSON files. For example, we generate the code reference of our AI framework Godot Steering Toolkit like so with the shell:
python -m gdscript-docs-maker ~/Repositories/godot-steering-toolkit/src/reference.json