Error using --gdscript-docs command tool

Iakobs commented 10 months ago

Tested versions

Reproducible in: 4.2 stable

System information

Windows 10

Issue description

Hi, I'm trying to generate the xml files of the docs for a plugin I'm developing, but when I run this command

godot --doctool <path_to_docs_folder> --no-docbase --gdscript-docs . (assuming I'm in the directory of the plugin, ie. /godot_project/addons/name_of_plugin)

I get a bunch of errors, as if the command tool was trying to run the project, but missing information. For example:

SCRIPT ERROR: Parse Error: Could not find type "PlayersClient" in the current scope.
          at: GDScript::reload (res://./autoloads/achievements_client.gd:114)
SCRIPT ERROR: Parse Error: Identifier "GodotPlayGameServices" not declared in the current scope.
          at: GDScript::reload (res://./autoloads/achievements_client.gd:43)
SCRIPT ERROR: Parse Error: Identifier "GodotPlayGameServices" not declared in the current scope.
          at: GDScript::reload (res://./autoloads/achievements_client.gd:44)
SCRIPT ERROR: Parse Error: Identifier "GodotPlayGameServices" not declared in the current scope.
          at: GDScript::reload (res://./autoloads/achievements_client.gd:47)
SCRIPT ERROR: Parse Error: Identifier "GodotPlayGameServices" not declared in the current scope.
          at: GDScript::reload (res://./autoloads/achievements_client.gd:48)
SCRIPT ERROR: Parse Error: Cannot infer the type of "safe_array" variable because the value doesn't have a set type.
          at: GDScript::reload (res://./autoloads/achievements_client.gd:48)
SCRIPT ERROR: Parse Error: Identifier "GodotPlayGameServices" not declared in the current scope.
          at: GDScript::reload (res://./autoloads/achievements_client.gd:55)

And then, the xml files are not generated.

Steps to reproduce

cd into plugin folder (if you are using the Minimal reproduction Project, it's addons/GodotPlayGameServices. If you download the plugin from the repo, it's plugins/export_scripts_template
Execute command godot --doctool <path_to_docs_folder> --no-docbase --gdscript-docs .

Minimal reproduction project (MRP)

You can download the repo of the plugin, I tested using this specific commit: https://github.com/Iakobs/godot-play-game-services/commit/92adb37ddff5d9dad6f6e5f9a366434445de9ed8

The classes I want to convert to xml are in the plugin/export_scripts_template folder.

I have also attached a zip with the godot project, there I tried executing the doctool inside the addons/GodotPlayGameServices folder.

mrp.zip

donn-xx commented 7 months ago

I didn't even know there was a doctools kinda thing! I have been making a plugin in gdscript and just using the inline remarks seems to create automatic docs which are pretty good. Not sure about C# and so on.

https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_documentation_comments.html

Iakobs commented 7 months ago

I didn't even know there was a doctools kinda thing! I have been making a plugin in gdscript and just using the inline remarks seems to create automatic docs which are pretty good. Not sure about C# and so on.

https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_documentation_comments.html

Hi! That works fine for in-editor docs, but the command line tool is supposed to generate the xml files that then you can use to create a static website (with parsing of the xml files, etc), like the godot online documentation itself.

donn-xx commented 7 months ago

Ah, okay. I never quite understood that because those help docs are not visible in-engine. I wish the gdscript help was, for example. What do you gain by this for your plugin? Am I missing some obvious help button somewhere?

Iakobs commented 7 months ago

@donn-xx it's not that I gain much, just the possibility of having a static website with the docs of the plugin to make it easier to check them, so you don't have to actually download the plugin to your project and activate it if you want to see what it does beforehand.

tracefree commented 7 months ago

I used the MRP privided in the .zip file and followed the instructions to reproduce the problem, using Godot 4.2.1. on Linux. I also see a bunch of GDScript compilation errors when running the command. When running the command from the root folder of the project (where project.godot is located) it does create three .xml files for me, two of them as hidden files:

JsonMarshaller.xml .--scenes--snapshots--Snapshots.gd.xml .--addons--GodotPlayGameServices--dock.gd.xml

When running the command from within addons/GodotPlayGameServices, it creates these two .xml files instead:

JsonMarshaller.xml .--dock.gd.xml

In both cases this is not the expected behavior, as many other classes are missing, and none of the generated files should be hidden. There is also no helpful error message. So I would say I can confirm this as being a bug.

tracefree commented 7 months ago

This may be related to #84579? The workaround mentioned in this comment seems to work, i.e. execute the command from the root project folder with the argument --gdscript-docs res://. This seems to generate complete documentation for all of the classes in the MRP. The console output says "No plugin found!" and nothing else, and the program doesn't terminate (had to stop it with Ctrl+C) but it did generate the .xml file.

bitwes commented 2 months ago

Ran into this when attempting to generate the documentation for GUT

Godot v4.3.stable - macOS 14.4.1 - Vulkan (Forward+) - integrated Apple M1 Pro - Apple M1 Pro (10 Threads)

This may be related to https://github.com/godotengine/godot/issues/84579? The workaround mentioned https://github.com/godotengine/godot/issues/84579#issuecomment-1873346477seems to work, i.e. execute the command from the root project folder with the argument --gdscript-docs res://.

This worked for me. I also had to ctrl+c to kill it, but things were generated. I have not investigated the resulting xml yet, but files of various sizes exist where I expected them to.

Results for various commands

alias fcount='ls -l | grep -v ^l | wc -l'
alias dirsize='du -hd 1 | sort -rh'
alias godot=/Applications/Godot_4.3.app/Contents/MacOS/Godot

From the project root. Using relative path and --gdscript-docs causes a hard crash.

$ godot --doctool ./documentation/godot_doctools --gdscript-docs addons/gut

Godot Engine v4.3.stable.official.77dcf97d8 - https://godotengine.org

ERROR: Attempt to open script 'res://addons/gut/parameter_factory.gd' resulted in error 'File not found'.
   at: load_source_code (modules/gdscript/gdscript.cpp:1094)
ERROR: Failed loading resource: res://addons/gut/parameter_factory.gd. Make sure resources have been imported by opening the project in the editor at least once.
   at: _load (core/io/resource_loader.cpp:284)

================================================================
handle_crash: Program crashed with signal 11
Engine version: Godot Engine v4.3.stable.official (77dcf97d82cbfe4e4615475fa52ca03da645dbd8)
Dumping the backtrace. Please include this when reporting the bug to the project developer.
[1] 1   libsystem_platform.dylib            0x000000019ca1b584 _sigtramp + 56
[2] Main::start() (in Godot) + 16228
[3] main (in Godot) + 344
[4] 4   dyld                                0x000000019c6620e0 start + 2360
-- END OF BACKTRACE --
================================================================

From the project root. Using the absolute path to the directory generates a lot of errors, and hangs, but it does generate SOME xml files, but not as many as when using res://addons/gut (probably missing all the ones it errors on).

$ godot --doctool ./documentation/godot_doctools --gdscript-docs /Users/me/development/godot/guts/Gut/addons/gut
Godot Engine v4.3.stable.official.77dcf97d8 - https://godotengine.org

ERROR: Attempt to open script 'res://addons/gut/warnings_manager.gd' resulted in error 'File not found'.
   at: load_source_code (modules/gdscript/gdscript.cpp:1094)
ERROR: Failed loading resource: res://addons/gut/warnings_manager.gd. Make sure resources have been imported by opening the project in the editor at least once.
   at: _load (core/io/resource_loader.cpp:284)
SCRIPT ERROR: Invalid access to property or key 'disabled' on a base object of type 'null instance'.
          at: _static_init (res://gut_loader.gd:51)
...
SCRIPT ERROR: Parse Error: Identifier "GutUtils" not declared in the current scope.
          at: GDScript::reload (res://doubler.gd:307)
SCRIPT ERROR: Parse Error: Identifier "GutUtils" not declared in the current scope.
          at: GDScript::reload (res://doubler.gd:310)
ERROR: Failed to load script "res://doubler.gd" with error "Parse error".
   at: load (modules/gdscript/gdscript.cpp:2936)

< hangs here, must ctrl+c to kill it >
$ fcount 
    57
$ dirsize
    260K

From the project root. Using res://addons/gut prints the Godot version and hangs, but it does generate the xml files.

$ godot --doctool ./documentation/godot_doctools --gdscript-docs res://addons/gut
Godot Engine v4.3.stable.official.77dcf97d8 - https://godotengine.org

<hangs here, must ctrl+c to kill it>
$ fcount 
    98
$ dirsize
   516K

godotengine / godot