Skip to content

Conversation

Ivorforce
Copy link
Member

@Ivorforce Ivorforce commented Sep 24, 2025

The current documentation for documentation in godot-cpp covers everything that's necessary, but there are several things I'd like to improve:

  • The information about version compatibility is too extensive, and distracts from important information. People will either use 4.3 or newer, and read the article, or use 4.2 or lower, and skip it via the disclaimer.
  • The disclaimer about assumptions of the article (e.g. with the file structure) is not needed. The actual assumptions we need are just that there is a demo folder. Listing more assumptions than needed distracts from the contents, and might unnecessarily scare away potential readers.
  • The Documentation styling section is duplicate to the "Class Reference Primer". The format used by Godot's class reference is the exact same as it is for GDExtension. We do not need this information twice.
  • I adjusted wording to the new structure, and hopefully made it easier to read.
  • I've also added a link to the documentation guidelines. While it's written for potential contributors, it's also a good reference for writing docs for GDExtensions.

@Ivorforce Ivorforce added enhancement area:manual Issues and PRs related to the Manual/Tutorials section of the documentation topic:gdextension labels Sep 24, 2025
@Ivorforce
Copy link
Member Author

Ivorforce commented Sep 24, 2025

For quick reference, here's the (current) new version:

SCR-20250924-mzmn

@Ivorforce Ivorforce force-pushed the simplify-godot-cpp-class-ref branch 3 times, most recently from 9636557 to 4c70c98 Compare September 24, 2025 13:35
@Ivorforce Ivorforce force-pushed the simplify-godot-cpp-class-ref branch from 4c70c98 to 882e2d8 Compare September 24, 2025 13:36
constants, signals, and more.

.. note::
To get started, identify your project's ``demo`` folder, which should contain a Godot project with your extension
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think in this case we should just say "identify your project's demonstration or testing project folder" since otherwise I see some people being confused that they need a demo folder

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about "identify your project's test project folder"?


.. image:: img/gdextension_docs_generation.webp

Documentation styling
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should not be deleted as there is an overlap with the general RichText documentation but not every tag works in the GDExtension documentation. I tested every tag and wrote down each one that works.

Copy link
Member Author

@Ivorforce Ivorforce Sep 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added a link to Class reference primer, which is what these files are. It is unrelated to the RichtText format (although there is some overlap).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see. There's no img or colorsupport in the class reference primer though as I see but are supported by the GDExtension docs system though.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps the documentations are just missing this piece of information?
Since I think it's using the same system, I'd be surprised if there were features in GDExtension docs that aren't supported by Godot's class reference.

`godot-docs <https://github.com/godotengine/godot-docs>`_ uses `Sphinx <https://www.sphinx-doc.org/en/master/>`_.
You can use the repository as a basis to build your own documentation system.
The following guide describes the basic steps, but they are not exhaustive:
You will need a bit of personal insight to make it work.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is meant here by personal insight? That seems unclear

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The idea was to communicate that the tutorial is not "complete", and whoever wants to publish their documentation will need to put in additional work beyond what the tutorial covers. Phrasing it like this was suggested back when this was added.

Comment on lines +43 to +45
The if-statement avoids adding the documentation to release builds of your GDExtension, where it is not needed.
SCons then loads all the XML files inside the ``doc_classes`` directory, and appends the resulting targets
to the ``sources`` array, to be included in your GDExtension build.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The if-statement avoids adding the documentation to release builds of your GDExtension, where it is not needed.
SCons then loads all the XML files inside the ``doc_classes`` directory, and appends the resulting targets
to the ``sources`` array, to be included in your GDExtension build.
The ``if`` statement avoids adding the documentation to release builds of your GDExtension, where it is not needed.
SCons then loads all the XML files inside the ``doc_classes`` directory, and appends the resulting targets
to the ``sources`` array, to be included in your GDExtension build.

Comment on lines +81 to +83
You can use the repository as a basis to build your own documentation system.
The following guide describes the basic steps, but they are not exhaustive:
You will need a bit of personal insight to make it work.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
You can use the repository as a basis to build your own documentation system.
The following guide describes the basic steps, but they are not exhaustive:
You will need a bit of personal insight to make it work.
You can use the repository as a basis to build your own documentation system.
The following guide describes the basic steps, but they are not exhaustive;
you will need a bit of personal insight to make it work.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area:manual Issues and PRs related to the Manual/Tutorials section of the documentation enhancement topic:gdextension
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants