When using GDScript's type inference, we should try to do simple inference as well.

This will only work for built-in types (int, float, etc.), calls to constructors, or when using a class name, e.g. var speed: = Vector2.ZERO

For instance an @discard or @ignore mark on a given line

The table is probably lacking a header or a first line to render as a table. There are apparently markdown parsers that do not support tables without headers.

Possible solutions

Render setget as a bullet list:

• Setter: set_value
• Getter: get_value

Use html instead of markdown:

<table>
<tr>
    <td>Setter</td>
    <td>set_value</td>
</tr>
<tr>
    <td>Getter</td>
    <td>get_value</td>
</tr>
</table>

Razoric coded a script that can run from the command line. We could use a POSIX/sh script for us Linux and MacOS users

Compared to the normal markdown output, for hugo, you need:

• No h1 title, hugo templates generally handle that
• Hugo has its own shortcodes, e.g. for code blocks and code highlighting.
• A header as json, toml, or yaml. For the website, we only use toml, but we can easily support other markups by using file templates:

+++
title = "{title}"
description = {decsription}
author = "{author}"
date = "{date}"
+++

For date formatting:

"{:%Y-%m-%d %H:%M:%S}".format(datetime.datetime())

Hello every body, and thank's for the work !

I'm submitting a...

• Bug report.
• Feature request.

Bug report

What is the current behavior?

Using Debian/Linux, the generate_reference script doesn't work.
I have made these changes at the end of your file :

1. first changing
   python3 -m gdscript_docs_maker "$($godot_project_dir)/reference.json"
   by this one
   python3 -m gdscript_docs_maker "$godot_project_dir/reference.json"
2. your output_dir option doesn't copy de .md files in any folders. Also I add this at the end :
   mv export/* "$output_directory"

Thanks again for all you did,
cheers, Pskalou

angle_to_vector2

**static** func angle_to_vector2(angle: float) -> Vector2

Returns a directional vector from the given orientation angle.

This assumes orientation for 2D agents or 3D agents that are upright and
rotate around the Y axis.

Is this the intended format? It makes the asterisks look a little superfluous, or like an error in formatting. Though on the flip side, without the code block, this makes the signature blend in.

angle_to_vector2

static func angle_to_vector2(angle: float) -> Vector2

Returns a directional vector from the given orientation angle.

This assumes orientation for 2D agents or 3D agents that are upright and
rotate around the Y axis.

What about a quote with > ?

angle_to_vector2

static func angle_to_vector2(angle: float) -> Vector2

Returns a directional vector from the given orientation angle.

This assumes orientation for 2D agents or 3D agents that are upright and
rotate around the Y axis.

Currently, static functions are being skipped over entirely.

While the ReferenceCollector successfully grabs static functions and puts them in a class' static_functions array, they are conspicuously missing from the markdown.

To make the docs maker as flexible as possible, we'd like to support having JSON keys or metadata on top of the one generated by the tool. That is to say, extra fields that may not be in the tool, like code examples, links to tutorials, references... extra information that would clutter the source code.

Current output:

vector3_to_angle (static)

func vector3_to_angle(vector: Vector3) -> float

Methods and static functions are about the same, but they use separate objects and markdown conversion function. Instead, an enum and one property would be enough to distinguish them:

class FunctionTypes(Enum):
...

@dataclass
class Function:
    type: FunctionTypes

A user sent me a reference.json file built from Godot that's missing some description keys, preventing the program from generating the reference. At first glance it looks linked to enums and godotengine/godot#35976

See https://github.com/GDQuest/godot-3d-mannequin/blob/master/CHANGELOG.md for reference

See https://packaging.python.org/tutorials/packaging-projects/ for reference

func add(behavior: GSTSteeringBehavior, weight: float) -> null

Admittedly, the JSON marks this as null as in no-return-type, but we should probably catch it to be void when it's a return type.

We should get the project version when generating the code reference, so users know which version of the tool they're reading docs for. Also, this could allow more complex projects to keep several major versions of their tools' docs in parallel, like Godot has 2.x, 3.0, 3.1, stable, and latest branches. I.e. they could output several files based on the project's Godot version.

It should be extracted from project.godot, I believe there's a version string in there.

So I installed gdscript-docs-maker using python pip like you say I should in README.
And Try to run it.

1. My system can find any generate_reference so add download it
2. I run it but it fails and generate empty script called ReferenceCollectorCLI.gd
3. So I download all your zip find this that there are dir godot-scripts and I need to copy to of them to my project - Why main README don't say about this?
4. I try to run ReferenceCollector.gd , but there are error in at line 29 that Collector.print_pretty_json() don't have specified type so I remove :
5. I try to run this script again, but there are error at the same line again that Collector.print_pretty_json() don't take 2 arguments so I remove true
6. I try to run this script again and it works and generete reference.json
7. I run generate_reference, but now I get this:

cat: godot-scripts/ReferenceCollectorCLI.gd: Nie ma takiego pliku ani katalogu
/home/jeremi360/Apps/Scripts/generate_reference: 81: test: !=: unexpected operator
'/tmp/tmp.Xod6Pu56k2' -> './ReferenceCollectorCLI.gd'
cp: nie można wykonać stat na 'godot-scripts/Collector.gd': Nie ma takiego pliku ani katalogu
Generating reference json data...
ERROR: start: Can't load script 'ReferenceCollectorCLI.gd', it does not inherit from a MainLoop type.
   At: main/main.cpp:1585.
ERROR: ~List: Condition "_first != __null" is true.
   At: ./core/self_list.h:112.
ERROR: ~List: Condition "_first != __null" is true.
   At: ./core/self_list.h:112.
WARNING: cleanup: ObjectDB Instances still exist!
   At: core/object.cpp:2071.
ERROR: clear: Resources Still in use at Exit!
   At: core/resource.cpp:476.
Done.
usunięty './ReferenceCollectorCLI.gd'
rm: nie można usunąć './Collector.gd': Nie ma takiego pliku ani katalogu
Generating markdown files in export
mkdir: utworzony katalog 'export'
/usr/bin/python3: No module named gdscript_docs_maker

And also why it removes Collector.gd now I need to copy it again - it can be frustrating if I want to make a few to times because I saw that I need to fix some thing.

This will wrap up #15, but I think the markdown code could use some refactoring to that end. Until now, we wrote the markdown document sequentially, but now we need to:

1. Process every description to find and replace links.
2. Pass the GDScriptClasses object around to search the cached class/symbol index.

Create an index.md or _index.md file that gives a TOC and links to the classes in the reference: once converted to html:

# Project name: version

Project description

* Base Types
  - [[GSTAgentLocation]]
  - [[GSTSteeringAgent]]
  - [[GSTTargetAcceleration]]
  - [[GSTPath]]
  - [[GSTUtils]]
* Individual Behaviors
  - [[GSTSteeringBehavior]]
  - [[GSTSeek]]
  - [[GSTFlee]]
  - [[GSTArrive]]
  - [[GSTPursue]]
  - [[GSTEvade]]
  - [[GSTMatchOrientation]]
  - [[GSTFace]]
  - [[GSTLookWhereYouGo]]
  - [[GSTFollowPath]]
* Group Behaviors
  - [[GSTGroupBehavior]]
  - [[GSTAvoidCollisions]]
  - [[GSTCohesion]]
  - [[GSTSeparation]]
* Combination Behaviors
  - [[GSTBlend]]
  - [[GSTPriority]]
* Proximities
  - [[GSTProximity]]
  - [[GSTRadiusProximity]]
  - [[GSTInfiniteProximity]]

Even if you remove the categories, it would already look a lot better than the wiki's Pages dropdown, and we could introduce formatting options.

Inner classes are currently not parsed and supported when parsing the json data. We should parse them recursively.

We could have a tool similar to Godot's doctool, that gives a table with the docs progress and missing docstrings.

We can add methods on Element and GDScriptClass to report that information easily. Then, a new module should take care of reading and logging that information.

The logic applied to variables and class descriptions should probably be applied to methods as well.

# Returns the `acceleration` modified with the behavior's desired amount of  
# acceleration.

Returns the acceleration modified with the behavior's desired amount ofacceleration.

It also breaks new lines for more laid out examples:

# Returns a number of neighbors based on a `callback` function.
#
# `_find_neighbors` calls `callback` for each agent in the `agents` array and
# adds one to the count if its `callback` returns true.
# virtual

Returns a number of neighbors based on a callback function._find_neighbors calls callback for each agent in the agents array andadds one to the count if its callback returns true.

The reasoning is that if someone is to call .new(), Godot will only complain about the wrong number of arguments, but not what those arguments should be. Can't exactly rely on intellisense to document our code for us.

    {
        "GSTPath.gd": {
            "is_tool": false,
            "class_name": "GSTPath",
            "extends": "Reference\n",
            "docstring": [
                "Represents a path made up of Vector3 waypoints, split into path segments for use by path\n",
                "following behaviors.\n"

Edit: Extends should probably be more like a class type.

We currently have a Virtual tag to mark virtual functions, but we could use some more tags. Some ideas:

• Marking deprecated features
• Marking removed features (e.g. having an outdated function greyed out?, with a version number)
• Indicating renamed functions and aliases, along with the version
• Indicating experimental or beta features

Possible markup:

# tags: virtual, deprecated

It makes a document rather dense. A particularly egregious example:

GSTUtils

Extends:

Description

Math and vector utility functions.

Properties

Methods

Signals

Enumerations

Property Descriptions

Method Descriptions

The program currently uses the gdscript file name for the class name. It should use the class_name in priority instead, and use the file name as a fallback.

Also, we need to parse the class's main docstring, with the possible form:

tool
class_name MyClass, path/to/icon
extends Node
# Docstring starts here

If a class extends, say Node, the program will link to a nonexistent page named Node.

The output contains signatures like:
{{< highlight gdscript >}}var orientation: float{{< / highlight >}}

even if -f markdown is used.

Fails:

λ gdscript_docs_maker --format markdown -p godot-steering-ai-framework ../godot-steering-ai-framework/project/reference.json
usage: GDScript Docs Maker [-h] [-p PATH] [-f FORMAT] [-d DATE] [-a AUTHOR]
                           [-v] [--dry-run]
                           files [files ...]
GDScript Docs Maker: error: unrecognized arguments: ../godot-steering-ai-framework/project/reference.json

Succeeds:

E:\Projects\Games\GDQuest\gdscript-docs-maker (master -> origin)
λ gdscript_docs_maker ../godot-steering-ai-framework/project/reference.json --format markdown -p godot-steering-ai-framework

λ 

This feature should probably be part of the docs merge tool.

It'd be nice to have some metadata to:

• Display the version of the project in the generated markdown. We can get that from project.godot. See #36, it needs to be done first
• Detect new, modified, or removed features in a given update. That would happen comparing the version numbers and/or changes upon merging the data.
• We can then add a metadata field to each relevant json object to add a [configurable] new html tag and css class name to the entries in the generated markdown

See merge_json.py to write that code.

Ignore set/get functions starting with a _

This is fine for the CLI version of the ReferenceCollector, because a brand new instance of Godot is opened for it every time.

But for the EditorScript ReferenceCollector, if the script changes, the code symbols are not updated until Godot is relaunched, or the cache somehow triggered. But we do have access to the language server's parse_local_script for that purpose to update it.

The tool should optionally include or ignore built-in methods such as _process, that are not part of a GDScript framework's public API.

Also, the tool should skip private functions. The convention in Godot is that one leading underscore stands for virtual, i.e. a function that you're meant to override. So we could use two leading underscores, i.e. __symbol, to mark private methods, subclasses, and properties.

I'd rather stick to one underscore, _, as in Python, for private. I think that we can differentiate them from virtual functions if the function either returns or, ideally, passes:

func _virtual_function():
    pass

@Razoric480 any thoughts on that?

The latest version of the program supports cross-references like [ClassName.method], etc. but the links don't always work. Part of the problem cannot be fixed without input from the user.

The problem

When previewing markdown documents on your desktop, the links should point to markdown files to work, as you're browsing through your file system. E.g. ClassName.md

If you convert to html and/or put the files on the web, the links should point to the page's name or file, ./ClassName or ./ClassName.html or the lowercase equivalents.

Hugo may change the case of the links depending on the website's settings I believe?

Solution

For markdown, I'm currently linking to ../PageName. This should work if you put your pages online with a CMS, but it won't if you output your files as html directly. To solve this, we might need to have an html output that writes links as ../pagename.html#header-name. We can look at how Sphinx and the Godot docs handle that.

In the hugo format, links should probably use the {{< relref >}} shortcode. This shortcode takes a relative path to a markdown document and resolves the final path for you. We have the exact name of the markdown documents so this would work reliably.

We should have a way to log the work the tool is doing, with different verbosity levels, and a corresponding command line option.

Instead of having Extends: ParentClass, we could have all the hierarchy of parents: Extends: Parent < Grandparent < ...

Also, extended classes could link to the corresponding documents directly.

Currently, the tool looks for a res://src/ directory by default to generate the code reference. generate_reference copies CollectReferenceCLI.gd as-is, but if you have multiple projects, you might need to target different directories. E.g., res://addons/... for an add-on, or something other than src if you're not working at GDQuest. Ideally, the shell script should support that.

Add a new type of metadata: the category key. This is part of #29 and will allow us to group classes by category in the exported files.

In a way, that forces the one writing the documentation to add a docstring to every function, so it could be seen as a feature and not a bug. I'm not sure if that's intended behavior however, since variables are not included.

Currently the languageserver doesn't collect enum docstrings. But we can still have support for constants/enums.

This depends on a bug fix on Godot's master: godotengine/godot#35976

The tool doesn't collect information about constants at the moment. It should collect them, maybe separately from regular properties?

The tool currently doesn't gather enums, although they might need docs of their own.

We should also probably support documentation for each constant in an enum:

enum Modes {
# Uses a fast algorithm but does not preserve the input data's order
FAST,
# Use a slower algorithm that preserves the input data's order
PRESERVE_ORDER
}

The tool generates a flat list of markdown files. As we have all the class and markdown data, we could cross-reference other classes, methods, and properties when generating the reference.

Similar to the Godot reference: http://docs.godotengine.org/en/latest/classes/class_kinematicbody.html-l

The functionality of parsing GDScript symbols with documentations with javadoc liked behavior is already implemented by the GDScript language server.

I think you don't need to make another parser as you can dump all the informations to json with an editor plugin. The lsp using the original gdscript parser so it should be the best choice to do this kind of work.

To dump the script symbols to json you just need to call this api in your editor plugin

https://github.com/godotengine/godot/blob/096bf873bc44a942ba7d5c4e52bf089fda6fdd6b/modules/gdscript/language_server/gdscript_workspace.cpp#L46

gdscript_objects.py references a file named "utils" but this file doesn't exist, this file contains a method called build_re_pattern that also appears to be missing