Allow submitting documentation to the Godot editor

[dsnopek]

Godot PR godotengine/godot#83747 added support for submitting documentation to the Godot editor from a GDExtension.

This PR aims to give godot-cpp users a way to use that, ideally, in much the same way as documentation is provided by modules.

Here's how it works:

• Using PR Generate docs from GDExtensions using --gdextension-docs with --doctool godot#91518, developers can run godot --doctool ../ --gdextension-docs in their demo project (assuming the project is in a directory below their top-level extension code) which will generate a doc_classes/ directory
• Edit the XML files in the doc_classes/ directory
• Add something like this to their SConstruct:

  if env["target"] in ["editor", "template_debug"]:
    doc_data = env.GodotCPPDocData("src/gen/doc_data.gen.cpp", source=Glob("doc_classes/*.xml"))
    sources.append(doc_data)
  

• Recompile
• And that's it!

When the GDExtension is loaded into the editor, it will automatically submit the documentation XML.

I'm not totally sure how to add this in CMake, but I think we can do it in a similar way to how we run binding_generator.py from CMake. I'd really appreciate any help with that!

Original description

I'm not entirely sure how we should expose this to developers. What I have here presently, is mostly about being able to test that the functionality from the Godot PR works. This could certainly use some design help for how to expose the build-system part (both for SCons and cmake) as well as how the developer should trigger the registration.

We'll also probably need some tooling somewhere, to assist in generating the XML files for extension classes. It looks like godot --doctool doesn't include extension classes, so we'll either need to modify it so that it does, or come up with some other process.

[dsnopek]

Alright, I've figured out a reasonably nice way for developers to use this functionality, that is as simple and automatic as I could make it. So, I'm taking this out of draft - it's ready for review!

The one main thing I still need to figure out is handling CMake support, but I don't think that'll be too hard.

Feedback on the overall approach would be appreciated!

[Naros]

Hi @dsnopek, what about being able to read documentation for existing classes? For example, a custom extension/plug-in that may want to display the description associated with a specific Godot native, extension contributed, or script contributed class as part of their UI?

[dsnopek]

@Naros:

what about being able to read documentation for existing classes? For example, a custom extension/plug-in that may want to display the description associated with a specific Godot native, extension contributed, or script contributed class as part of their UI?

I don't think Godot gives us an API to read documentation, unfortunately. That would be something to propose for Godot, before we could do anything in godot-cpp. If it was through classes bound in ClassDB then even GDScript could use it?

Your PR godotengine/godot#90189 is probably the closest thing that exists presently, allowing editor plugins to show particular documentation to the user, but not actually read its content.

[akien-mga]

Tested this PR and the upstream godot one on my Threen extension:
akien-mga/threen#3

It works great, and out of the box! The instructions in the PR were clear.

Some minor issues / potential future work I noticed:

• The first time I loaded the editor with the extension with docs compiled in, the doc page was still not showing descriptions. Restarting the editor fixed it. I couldn't reproduce it again, I tried to remove the descriptions from the XML and recompile, it showed empty descriptions as expected, then I re-added them, recompiled, and it showed descriptions the first time. Might still have some issues playing nice with the editor doc cache or time of first loading the extension.

• const methods don't seem to get the qualifiers="const" attribute, unlike they do in the core engine.

• The XML header has xsi:noNamespaceSchemaLocation="../class.xsd" like upstream, but this is meant to be a path to the class.xsd file, which isn't valid for GDExtension which live outside the Godot repo. It seems like this field expects any URI, so we can maybe use a direct link to the GitHub file: https://raw.githubusercontent.com/godotengine/godot/master/doc/class.xsd

[akien-mga]

Source compatibility

Should we consider the use case of maintaining an extension that may want to make use of this new feature for builds using 4.3+ as baseline, while still keeping the possibility to build for older Godot versions when targeting an older godot-cpp commit?

This may require adding an API in the godot-cpp env like env.has_feature("doc_data") or exposing version information so that one could check if a feature is supported before trying to use it in SConstruct.

diff --git a/SConstruct b/SConstruct
index 4f19de1..781fc98 100644
--- a/SConstruct
+++ b/SConstruct
@@ -7,9 +7,10 @@ env = SConscript("godot-cpp/SConstruct")
 env.Append(CPPPATH=["src/"])
 sources = Glob("src/*.cpp")
 
-if env["target"] in ["editor", "template_debug"]:
-    doc_data = env.GodotCPPDocData("src/gen/doc_data.gen.cpp", source=Glob("doc_classes/*.xml"))
-    sources.append(doc_data)
+if env.has_feature("doc_data"):
+    if env["target"] in ["editor", "template_debug"]:
+        doc_data = env.GodotCPPDocData("src/gen/doc_data.gen.cpp", source=Glob("doc_classes/*.xml"))
+        sources.append(doc_data)
 
 if env["platform"] == "macos":
     platlibname = "{}.{}.{}".format(libname, env["platform"], env["target"])

Of course this wouldn't work right now for versions of godot-cpp before adding this add_feature method, so one would need to check the method exists too with hasattr or similar. But this could be a system for checking feature availability once 4.3+ is reasonably the baseline for most extensions.

Another approach that's already usable for this specific feature is simply a try/except approach like this:

diff --git a/SConstruct b/SConstruct
index 4f19de1..e18ff0e 100644
--- a/SConstruct
+++ b/SConstruct
@@ -8,8 +8,11 @@ env.Append(CPPPATH=["src/"])
 sources = Glob("src/*.cpp")
 
 if env["target"] in ["editor", "template_debug"]:
-    doc_data = env.GodotCPPDocData("src/gen/doc_data.gen.cpp", source=Glob("doc_classes/*.xml"))
-    sources.append(doc_data)
+    try:
+        doc_data = env.GodotCPPDocData("src/gen/doc_data.gen.cpp", source=Glob("doc_classes/*.xml"))
+        sources.append(doc_data)
+    except AttributeError:
+        print("Not including class reference as we're targeting a pre-4.3 baseline.")
 
 if env["platform"] == "macos":
     platlibname = "{}.{}.{}".format(libname, env["platform"], env["target"])

[akien-mga]

Code looks good, and I tested the feature which works great.

[dsnopek]

@akien-mga Thanks for doing such extensive testing and review!

• The first time I loaded the editor with the extension with docs compiled in, the doc page was still not showing descriptions. Restarting the editor fixed it. I couldn't reproduce it again, I tried to remove the descriptions from the XML and recompile, it showed empty descriptions as expected, then I re-added them, recompiled, and it showed descriptions the first time. Might still have some issues playing nice with the editor doc cache or time of first loading the extension.

I also encountered this (but only two times), and I also suspect something with the doc cache. This needs more investigation, but I don't think the problem is on the godot-cpp side, so I think it's out-of-scope for this PR.

• const methods don't seem to get the qualifiers="const" attribute, unlike they do in the core engine.

This turned out to be a godot-cpp bug: I've added a fix for this in my latest push!

Should we consider the use case of maintaining an extension that may want to make use of this new feature for builds using 4.3+ as baseline, while still keeping the possibility to build for older Godot versions when targeting an older godot-cpp commit?

This may require adding an API in the godot-cpp env like env.has_feature("doc_data") or exposing version information so that one could check if a feature is supported before trying to use it in SConstruct.
[snip]
Another approach that's already usable for this specific feature is simply a try/except approach like this:

Maybe we can recommend the try/except approach for now, and consider something more organized for later?

As far as "recommending" the approach, I considered putting it into test/SConstruct, but that isn't really an example anymore, since we converted it into just automated tests (in PR #1101). I guess it should be added to https://github.com/godotengine/godot-cpp-template?

[akien-mga]

• const methods don't seem to get the qualifiers="const" attribute, unlike they do in the core engine.

This turned out to be a godot-cpp bug: I've added a fix for this in my latest push!

Tested and confirmed the fix, I got three methods in Threen with the const qualifier added.

Another approach that's already usable for this specific feature is simply a try/except approach like this:

Maybe we can recommend the try/except approach for now, and consider something more organized for later?

Sounds good yeah.

As far as "recommending" the approach, I considered putting it into test/SConstruct, but that isn't really an example anymore, since we converted it into just automated tests (in PR #1101). I guess it should be added to https://github.com/godotengine/godot-cpp-template?

Yes I think we could add this to godot-cpp-template.

[akien-mga]

Thanks!