Repository navigation
CMake build scripts only generate documentation for the first XML file in doc_classes/ #123
Description
Activity
Just to make sure I understand correctly:
The
ExampleClassis not registered in your extension, but theSummatorandTrafficLightclasses are. When you built your extension with theExampleClass.xml, then all the docs failed to load. But, then when you rebuild withoutExampleClass.xml, then the docs for the other classes load.Is that correct?
If so, I wonder if the full documentation import is failing because there's a class that doesn't exist in the data. This would be a Godot bug, rather than a bug in the template.
Reacted by Lukas TenbrinkNo, example class was included in register_types still.
Basically clone template, add summator and traffic light classes from your Godotcon 2024 presentation, add docs for summator and or traffic light, launch, no docs. delete ExampleClass.xml, relaunch and documentation is there. Add the example class XML file back and relaunch documentation goes away.
I can put an example in a repo if you want.
But it happens every time for me. I went through three clones of the template yesterday trying to figure out why the documentation wouldn't load till I realized that the working project did not have a ExampleClass.xml file.
Note there are nor errors or warnings from Godot, like when documentation is malformed, so my thought would be the docs are loading, just not available, but that's just a guess. And yes I'm not sure if this is template related or Godot related.
Edit:
Now I'm not sure it is loading the documentation. If I intentionally malform the documention and run the project without the ExampleClass.xml I get this error:ERROR: Condition "parser->get_node_name() != "class"" is true. Returning: ERR_FILE_CORRUPTHowever if I add ExampleClass.xml back to doc_classes then not only do I not get the the documentation, but it no longer throws the file corrupt error.
This is one strange problem, but it looks like it may be engine related and not template related. I cloned the initial project I had trouble in, and changed the name of example class to ZedClass to see if the order of the xml files made a difference. I also changed the order or class registration.
After launching things are fine. I close Godot, use Godot to generate some documentation. After generating the docs, if I relaunch the documentation disappears again.
If I then delete the ZedExample.xml file and relaunch. the documentation for the Summator and TrafficLight works again. It also still happens if I don't register the ZedExample class but leave the xml file there.
If you restart the editor a few times (without deleting any files), do you sometimes get different results each time?
That's actually something I've personally seen in the past, and I think it may be related to the editor's documentation cache and timing.
Or, can it only be triggered my adding/removing the XML file, rebuilding, and restarting?
Only adding / removing the xml documentation for the class in question changes anything. Once the project is built it exhibits the same behavior until it is rebuilt with / without the xml documentation for the example class.
Edit:
I was mistaken, removing the example class docs allows the next in line to be displayed, but 1 and only 1 class ever gets it's documentation added. It seems to be a problem in the godot-cpp bindings cmake scripts. I added a few messages to the configure and see that even though the template's cmake file correctly includes all the files in the doc_classes, the doc generation function in the cpp bindings (GodotCPPModulle.cmake - line 127) only ever lists one file to generate documentation for.
perhaps someone can pass this along. Building with scons works as advertised.
I was mistaken, removing the example class docs allows the next in line to be displayed, but 1 and only 1 class ever gets it's documentation added. It seems to be a problem in the godot-cpp bindings cmake scripts.
Aha, thanks for debugging!
I'm going to rename and move this issue over to the godot-cpp repo
- changed the title
[-]exampleClass.xml prevents class documentation from loading[/-][+]CMake build scripts only generate documentation for the first XML file in `doc_classes/`[/+]on May 18, 2026 I looked into it a little more and I think it affects both projects. In CMakeLists.txt for the template there is this block of code:
# conditionally add doc data to compile output if(DOC_XML) if(GODOTCPP_TARGET MATCHES "editor|template_debug") target_doc_sources(${LIBNAME} ${DOC_XML}) endif() endif()Which calls this:
#[[ target_doc_sources A simpler interface to add xml files as doc source to a output target. TARGET: The gdexension library target SOURCES: a list of xml files to use for source generation and inclusion.]] function(target_doc_sources TARGET SOURCES) # set the generated file name set(DOC_SOURCE_FILE "${CMAKE_CURRENT_BINARY_DIR}/gen/doc_source.cpp") # Create the file generation target, this won't be triggered unless a target # that depends on DOC_SOURCE_FILE is built generate_doc_source( "${DOC_SOURCE_FILE}" ${SOURCES ) # Add DOC_SOURCE_FILE as a dependency to TARGET target_sources(${TARGET} PRIVATE "${DOC_SOURCE_FILE}") # Without adding this dependency to the doc_source_generator, XCode will complain. add_dependencies(${TARGET} generate_doc_source) endfunction()Now when the template's CMakeLists.txt passes the
${DOC_XML}it is not in quotes, so doesn't this mean it will be expanded and each list item become a separate arg to the function?Same with when the above function calls generate_doc_source, it passes the variable as is instead of in quotes, meaning generate_doc_source gets an argument for each item in the list or is this not the case?
Adding the quotes in those two places, doing a clean, and re-configuring seemed to fix it for me. For whatever reason without the clean and reconfigure after adding the quotes results in a weird message:
ERROR: Invalid tag in doc file: class. at: _load (editor/doc/doc_tools.cpp:1439)Reacted by Samuel Nicholasyeah I thought that quoting issue was fixed, I remember a PR related to quoting not long ago.
godotengine/godot-cpp#1918 was it, but i guess it wasn't fixed at that point and i forgot about it. sorry about that.
Looks like there is more to it than that, as it worked for me, and then stopped working, now it always throws the invalid tag error when loaded in the editor , or when running doctool:
at: _load (editor/doc/doc_tools.cpp:1439)This one was my bad sorry.
This one took a while to figure out as well, if the Summator documentation XML has an invalid tag, it prevents the TrafficLight documentation from loading or maybe compiling. I kept hunting in the Trafficlight's XML file for the problem because that was the one that didn't show up, but the problem was in the Summator xml where i used
<members />for an empty members block and it did not like that.Is this the way it's supposed to work, where an error in one class's documentation, causes the others to not load, but the one with the bad tag loads?
I feel bad now, sorry I forgot how old my version of the bindings was. Having to move this issue back and forth and all.
Again sorry for the extra work.Is it closed though?
I agree both instances seem to be fixed. But I just cloned this repository, literally just now, and the cpp bindings still have the problem, I thought maybe my cloned copy had been old, and that's why the quotes where missing in my bindings sub module.
Yet after a new clone of this template repository, the quotes are still missing in the bindings:
Since a sub-module points to a specific branch/tag/commit in the repository, does the sub-module need to be updated to point to a more recent branch?
Ah, the template still points to godot-cpp 4.4. We should probably update it to use v10, which also has the advantage of being able to support back to Godot 4.3. The question is if we think the current master of v10 is ready, or if we need to wait for the release
Reacted by Lukas TenbrinkI think we should update the template on v10 release. It is sort of ready, but there still the template updates I wanted to do (and keep not having time for) which might slightly break compat...
Godot version
4.6.1
godot-cpp version
6388e26
System information
Linux
Issue description
This one took me a while to figure out. I was working on some documentation generation, and noticed that in one project the XML files would load and in the other they wouldn't. After about an hour checking tool chains, and whatnot, the only difference I could find between the projects was that the one that was loading the documentation did not have the example class documentation. When I remove this file in the non-working project it then works.