Dump API docs from inline GDScript comments using --doctool --gdscript-docs PATH

[dsnopek]

Godot is now parsing inline API documentation in GDScript, in order to show it in the editor's integrated help system.

This PR allows dumping this as XML by passing --doctool --gdscript-docs PATH on the command-line, using the same XML format as --doctool normally does for the engine API documentation.

This could allow addon authors to further process the XML, for example, to create an online API reference.

I'm not 100% sure that having this in the engine is a good idea. It wouldn't be that hard to create an external tool that parsed GDScript's inline API documentation (like https://github.com/GDQuest/gdscript-docs-maker). The advantage to having it in engine is that it will exactly match what shows up in the editor's help system.

What do you think?

[groud]

The feature makes sense to me.

Cc @NathanLovato for the GDquest team, if that looks good to you as your team is working on documentation tooling.

[NathanLovato]

It does look good, though note that our tool was mostly to fill the gap for Godot 3, as having docs generated in the editor was the biggest need for us.

[akien-mga]

Didn't review in depth, but some comments:

• The feature makes sense to me 👍
• --doctool doesn't seem needed at all, is it? Just godot --gdscript-docs PATH should be sufficient.
• I'm not fond of breaking encapsulation and having code in main.cpp that depends on the GDScript module. We do have such a hack for Mono currently, so this isn't worse per se, but it's still adding more tech debt to our nasty main.cpp. The whole file requires a full overhaul if we want to make it possible for modules to define their own command line options though, so for now we might have to live with the hack.

[dsnopek]

Thanks for the review!!

--doctool doesn't seem needed at all, is it? Just godot --gdscript-docs PATH should be sufficient.

--doctool isn't strictly necessary, but I'm using it because:

1. It sets some flags we need set for --gdscript-docs anyway
2. It can set the output path if you give it an argument like --doctool PATH (like you can with normal --doctool usage). If we didn't use --doctool for this, we'd need to add another option like --gdscript-docs-output or something.
3. It's conceptually related (ie. we're generating docs XML) and combining --doctool with another option has a precedent with --no-docbase

That said, if you'd prefer that we didn't use --doctool and instead added a --gdscript-docs-output option, I'd be fine to update the PR for that! :-)

I'm not fond of breaking encapsulation and having code in main.cpp that depends on the GDScript module. We do have such a hack for Mono currently, so this isn't worse per se, but it's still adding more tech debt to our nasty main.cpp. The whole file requires a full overhaul if we want to make it possible for modules to define their own command line options though, so for now we might have to live with the hack.

Yeah, I'm not crazy about adding more junk to main.cpp either. I did it mainly because --doctool support is already embedded in main.cpp.

It'd be great to extract it, but we'd still need a way to affect how CLI arguments are parsed depending on if GDScript is enabled (since we wouldn't want to offer a --gdscript-docs option if there is no GDScript), and so to completely remove it, we'd need a new system that somehow allowed modules to hook into CLI parsing.

Anyway, I was hoping this could sneak in for now given that it's not too much code. :-) But let me know if this is blocker, and then I'll try to think up some options.

[akien-mga]

It can set the output path if you give it an argument like --doctool PATH (like you can with normal --doctool usage). If we didn't use --doctool for this, we'd need to add another option like --gdscript-docs-output or something.

I didn't notice that you actually needed two paths for this. Makes sense to use --doctool for the output path then.

Anyway, I was hoping this could sneak in for now given that it's not too much code. :-) But let me know if this is blocker, and then I'll try to think up some options.

No it's ok to proceed with the hack for now. A better system IMO depends on refactoring the whole of main.cpp, which is something I've wanted to do for a long time, but ENOTIME.

[mhilbrunner]

LGTM, and very useful feature.

I've seen it in use at W4 to create online docs for a Godot Addon. Having the same docs XML > Sphinx > ReadTheDocs workflow we already do but for Godot GDScript addons is potentially very cool.

I really want to see this integrated with a new version of the Asset Lib so people can get a online reference built for their addons automatically (optionally of course).

[akien-mga]

Thanks!