Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/gdquest/gdscript-docs-maker
Create documentation and class references from your Godot GDScript code
https://github.com/gdquest/gdscript-docs-maker
documentation documentation-tool gdscript godot godot-engine reference
Last synced: 3 days ago
JSON representation
Create documentation and class references from your Godot GDScript code
- Host: GitHub
- URL: https://github.com/gdquest/gdscript-docs-maker
- Owner: GDQuest
- License: mit
- Created: 2020-01-27T18:56:47.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2024-05-16T10:26:04.000Z (9 months ago)
- Last Synced: 2025-02-01T11:06:59.899Z (3 days ago)
- Topics: documentation, documentation-tool, gdscript, godot, godot-engine, reference
- Language: Python
- Size: 200 KB
- Stars: 268
- Watchers: 8
- Forks: 26
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# GDScript Docs Maker
[](https://github.com/GDQuest/gdscript-docs-maker) [](https://hub.docker.com/repository/docker/gdquest/gdscript-docs-maker)
# Introduction
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](https://daringfireball.net/projects/markdown/syntax) or [hugo](https://gohugo.io/) format. If you make plugins or a framework for Godot, GDScript Docs Maker will generate API reference documentation from your code.
**It is for Godot 3. The tool does not work with Godot 4.**
GDScript Docs Maker creates documents following Godot's built-in class reference. You can see an example with our [Godot Steering Toolkit documentation](https://gdquest.gitbook.io/godot-3-steering-ai-framework-reference/)
- [Usage](#usage)
* [Using the container image](#using-the-container-image)
* [Local installation](#local-installation)
* [Writing your code reference](#writing-your-code-reference)
* [Generating the markdown files](#generating-the-markdown-files)
* [Hugo output](#hugo-output)
- [The manual way](#the-manual-way)
+ [Converting JSON](#converting-json)
# Usage
GDScript Docs Maker can be either used using the official [Docker image](https://hub.docker.com/r/gdquest/gdscript-docs-maker) or by installing it locally. For the docker image, only [Docker](https://www.docker.com/get-started) is required.
For the local installation, Godot 3.2+ and Python 3.7+ are required. **Note that GDScript Docs Maker only works with Godot 3. It is not compatible with Godot 4.**
## Using the container image
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.
## Local installation
You can install the GDScript Docs Maker python package with pip:
```bash
# 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_maker
```
Although to use the shell script that simplifies creating the reference, `generate_reference`, you need to clone this repository. More on that below.
## Writing your code reference
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:
```gdscript
# 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.0
```
If you need long docstrings, you can use multiple commented lines:
```gdscript
## 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 GSAIKinematicBody2DAgent
```
## Generating the markdown files
We 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:
```bash
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](https://github.com/GDQuest/gdscript-docs-maker/releases).
- You need `godot` to be available on the [system PATH variable]().
## Hugo output
You can output markdown files for [hugo](https://gohugo.io/), the static website engine.
To do so, call GDScript docs maker with the `--format hugo` option. You can use two extra flags with this:
```bash
--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:
```bash
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/
```
# The manual way
If you want to generate the JSON and convert it manually, there are three steps involved:
1. Copying the GDScript files to your Godot project:
- `./godot-scripts/Collector.gd` and `./godot-scripts/ReferenceCollectorCLI.gd` or `./godot-scripts/ReferenceCollectorCLI.gd` for Godot 3
- `./godot-scripts/CollectorGd4.gd` and `./godot-scripts/ReferenceCollectorCLIGd4.gd` or `./godot-scripts/ReferenceCollectorCLIGd4.gd` for Godot 4
2. 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`).
3. Running `gdscript_docs_maker` on 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.
### Converting JSON
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](https://github.com/GDQuest/godot-steering-toolkit/) like so with the shell:
```fish
python -m gdscript-docs-maker ~/Repositories/godot-steering-toolkit/src/reference.json
```