Create documentation and class references from your Godot GDScript code.
GDScript Docs Maker
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 format.
If you make plugins or a framework for Godot, GDScript Docs Maker will help you save a lot of time documenting your code.
It creates documents following Godot's built-in class reference. You can see an example with our Godot Steering Toolkit documentation
Table of Contents
- Getting Started
- Hugo output
- The manual way
Note: This program requires Godot 3.2+ and Python 3.7+ to work.
You can install GDScript Docs Maker 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_maker
In this section, we're showing you how to use the program to generate a code reference quickly.
You need to:
- Write docstrings inside your GDScript code.
- Use one of the shell programs that ships with this add-on.
Writing your code reference
Document properties and functions with comment blocks placed on the line before their definition:
# 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
Your docstrings can be as long as you want.
Generating the markdown files
We wrote two shell scripts to automate the steps in generating a code reference:
./generate_reference.sh for Linux or MacOS, and
./generate_reference.bat for Windows.
Use either of them to quickly generate your code reference:
generate_reference.sh Generate a code reference from GDScript. Usage: generate_reference.sh $project_directory (optional)$output_directory Arguments: $project_directory -- path to your Godot project directory. This directory or one of its subdirectories should contain a project.godot file. $output_directory -- directory path to output the documentation into. Flags: -h/--help -- Display this help message.
godot to be available on the system PATH.
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/
The manual way
If you want to generate the JSON and convert it manually, there are three steps involved:
- Copying the GDScript files
./godot-scripts/ReferenceCollectorCLI.gdto your Godot 3.2 project.
- Running the GDScript code with Godot, either from the editor (
ReferenceCollector.gd) or by calling Godot from the command line (
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.
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
This document lists new features, improvements, changes, and bug fixes in every GDScript docs maker release.
GDScript Docs Maker 1.3.0
- Create an index page with a table of contents. To do so, use the new
--make-index. This generates an extra
- You can now link between classes, including to specific methods and
[symbol_in_this_class]and docs maker will replace it with a link to the corresponding page and heading.
- Add support for the class category
metadata: this allows you to group classes by categories. Add a line with# category: My Category` in your class's docstring to register a category for it.
- Classes now show all ancestors they extend, and the extends list links to the reference of parent classes.
- Store and write key project information: name, description, and human-readable
- We get them from the Application Settings in your Godot project.
- For the project version, in 3.2.0, you need to add it yourself as `application/config/version. It must be with the form "1.0.0". Future or more recent Godot versions should have this defined by default. Upon exporting your game, Godot should also use this version number.
- The Windows
generate_reference.batcommand-line script now supports command-line flags and arguments. The script also now checks for and prevents common errors.
extendsline if the class doesn't extend any type.
- Remove properties summary and methods summary if the class respectively doesn't have public properties or methods.
- Changed the default export directory to "export", as we use "dist" to build the program's pip package itself.
GDScript Docs Maker 1.2.1
- Move the pip package's configuration to
- The setup now automatically finds packages and data.
- This improves type checks and imports with mypy.
- The tool now outputs regular markdown code blocks instead of hugo shortcodes by default.
Collector.gdscript you can run from Godot's editor now rebuilds the language server cache so you don't need to restart Godot to rebuild the JSON class data.
- Fixed an error in markdown conversion when the Godot Language Server generates empty classes in the generated JSON file.
- If a class doesn't have a name, docs maker will now skip it.
GDScript Docs Maker 1.2
- Add code highlighting to the
--authorcommand line flags for the hugo front matter output.
- Add support for the
abstracttag, for abstract base classes.
- Add GDScript code highlighting for the hugo export format.
- Add support for enums.
- The documents now only have 1 empty line betweens paragraphs, headings, etc. instead of 2 to 4.
GDScript Docs Maker 1.1
- New output format for the static website engine hugo with toml front-matter. Use the
--format hugooption to select it.
--dry-runcommand-line option to output debug information.
- Use code blocks for functions instead of inline code.
GDScript Docs Maker 1.0
This is the initial release of the program. It can collect and generate a code reference from your Godot GDScript projects.
- Parses and collects docstrings from GDScript files, using Godot 3.2's Language Server. Outputs the data as JSON.
- Converts the JSON data to markdown files.
- Writes methods, static functions, signals, member variables, and class data.
- Only writes relevant sections. For example, the tool only creates a "Method Descriptions" section if there are methods in the class.
- Skips built-in callbacks, i.e.
- Skips the constructor,
_init, unless it has arguments.
- Skips private functions and member variables, unless tagged as virtual.
- Supports tags in the source code with the
tags:keyword followed by comma-separated strings, like
tags: virtual, deprecated.
- Currently, the program only takes
virtualinto account, but it does store all the tags.
- Currently, the program only takes
- There are two shell scripts for POSIX shells (sh, bash, etc.) and Windows CMD, respectively. Use them to generate your code reference instantly.
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|Filename, size||File type||Python version||Upload date||Hashes|
|Filename, size gdscript_docs_maker-1.3.0-py3-none-any.whl (6.0 kB)||File type Wheel||Python version py3||Upload date||Hashes View|
|Filename, size gdscript_docs_maker-1.3.0.tar.gz (6.3 kB)||File type Source||Python version None||Upload date||Hashes View|
Hashes for gdscript_docs_maker-1.3.0-py3-none-any.whl
Hashes for gdscript_docs_maker-1.3.0.tar.gz