Implement reStructuredText generation for online documentation of GDExtensions

[Ivorforce]

Describe the project you are working on

A gdextension.

Describe the problem or limitation you are having in your project

GDExtensions cannot currently generate online documentation akin to the godot docs. An online reference is an important alternative to in-editor documentation, especially before installation.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

GDExtensions should be able to generate online-compatible documentation, much like make rst for the godot engine itself.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

godot-cpp has recently acquired the capability to generate ingame docs files (doc_classes xml files), thanks to dsnopek. It should be possible to adapt some more of the godot engine documentation pipeline to generate rst files, that can be adapted by e.g. Sphinx to be hosted on a site.

I will be playing with the tool soon, especially as it tool may already support foreign docs to some capacity. If so, it could be integrated and / or its use documented for gdextensions that want to host documentation online.

If this enhancement will not be used often, can it be worked around with a few lines of script?

Not really, though you could manually set up sphinx, duplicating your documentation.

Is there a reason why this should be core and not an add-on in the asset library?

Docs are an important part of complex libraries, useful to all gdextensions.

[dsnopek]

This draft PR may also be interesting to you - it aims to put inline Doxygen comments in godot-cpp itself, so your IDE can help give you documentation: godotengine/godot-cpp#1311

[Ivorforce]

I came across the PR as I was researching for this. It would be an excellent addition, though it's orthogonal to what I propose here.

[dalexeev]

make_rst.py only reads XML files, so you can probably run it against GDExtension docs too.

[Ivorforce]

I tested make_rst.py. It complains a ton (because of unresolved godot types), and I had to add a version.py file to my own project to make it happy, but it does spit out correct looking .rst files. From here to sphinx docs should be pretty easy.

The approach, outlined

I think an easy first step should be to add an option to the script to ignore unresolved references. The best way to use it without cloning the repo may be the way poetry handles their installer:

curl -sSL https://raw.githubusercontent.com/godotengine/godot/master/doc/tools/make_rst.py | python3 - -o "doc/classes" -l "en" doc_classes

Finally, we'll need to add documentation for how to gdextensions should use the tool, including a section for a minimal sphinx (or similar) setup.

I don't think any of this will be a big burden to the existing tooling, so I'll just go forward prepare PRs in the next 1-2 weeks.

[Ivorforce]

I was able to build the docs into a readthedocs repo, mirroring the one godot uses: https://numdot.readthedocs.io/en/latest/index.html

To achieve this:

• Create docs/
• Add godot-docs as a submodule
• Copy over and modify conf.py, index.rst and .readthedocs.yaml, as well as a few assets.
• Build class references from .xml files with curl -sSL https://raw.githubusercontent.com/godotengine/godot/master/doc/tools/make_rst.py | python3 - -o "doc/classes" -l "en" doc_classes
• Create a readthedocs account, add the project and build it.

For anyone coming across here looking to create docs for their own gdextension, feel free to use my implementation as a template: https://github.com/Ivorforce/NumDot/tree/main/docs

I will consolidate this information into a wiki page to the gdextension docs page. It would be nice to have a 'simpler' way for adding docs without depending on the full godot docs repo, but for now this is an acceptable workflow.

[Ivorforce]

As godotengine/godot-docs#9966 is merged, the scope of this proposal will be fulfilled: Generating online documentation from the ingame documentation (.xml files) is now a treaded and loosely documented path. With this, I'll close this proposal.

To view the docs entry on the matter, visit the article GDExtension Docs System (the changes should be viewable soon).

The outlined workflow could certainly be better, but it could also be a lot worse. Any improvements to it should be separately proposed.