Skip to content

Simplify the "Adding documentation" article for godot-cpp, and de-duplicate format information. #11319

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+38 −148
Open

Simplify the "Adding documentation" article for godot-cpp, and de-duplicate format information. #11319

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
186 changes: 38 additions & 148 deletions tutorials/scripting/cpp/gdextension_docs_system.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,180 +5,67 @@ Adding documentation

.. note::

Adding documentation for GDExtensions is only possible for Godot 4.3 and later. The support can be integrated into your project
regardless because the snippet will check if you use the appropriate godot-cpp version.
If you set the ``compatibility_minimum`` to 4.2 and you load a project with the extension through a 4.2 editor, the
documentation page for that class will be empty. The extension itself will still work.
Adding documentation for GDExtensions is only possible with Godot 4.3 and later.

The GDExtension documentation system works in a similar manner to the built-in engine documentation. It uses a series of
XML files (one per class) to document the exposed constructors, properties, methods, constants, signals, and theme items of each class.
The GDExtension documentation system works in a similar manner to the built-in engine documentation: It uses
:ref:`XML files <doc_class_reference_primer>` (one per class) to document the exposed constructors, properties, methods,
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"?

installed and working. If you are using `godot-cpp-template <https://github.com/godotengine/godot-cpp-template>`__, your
GDExtension project already has a ``demo`` folder. Alternatively, you can add one by following the steps
described in :ref:`doc_godot_cpp_getting_started`.
Inside the ``demo`` folder, run the following terminal command:

We are assuming you are using the project files explained in the :ref:`example project <doc_godot_cpp_getting_started>`
with the following structure:

.. code-block:: none

gdextension_cpp_example/ # GDExtension directory
|
+--demo/ # game example/demo to test the extension
| |
| +--main.tscn
| |
| +--bin/
| |
| +--gdexample.gdextension
|
+--godot-cpp/ # C++ bindings
|
+--src/ # source code of the extension we are building
| |
| +--register_types.cpp
| +--register_types.h
| +--gdexample.cpp
| +--gdexample.h

Inside the Godot demo project directory of your GDExtension directory, run the following terminal command:

.. code-block:: none
.. code-block:: shell

# Replace "godot" with the full path to a Godot editor binary
# if Godot is not installed in your `PATH`.
godot --doctool ../ --gdextension-docs

This command calls upon the Godot editor binary to generate documentation via the ``--doctool``
and ``--gdextension-docs`` commands. The ``../`` addition is to let Godot know where the GDExtension
SConstruct file is located. By calling this command, Godot generates a ``doc_classes`` directory inside the
project directory in which it generates XML files for the GDExtension classes. Those files
can then be edited to add information about member variables, methods, signals, and more.
This command instructs Godot to generate documentation via the ``--doctool`` and ``--gdextension-docs`` commands.
The ``../`` argument specifies the base path of your GDExtension.

After running this command, you should find XML files for your registered GDExtension classes inside the ``doc_classes``
folder in your GDExtension project. You could edit them now, but for this tutorial, the empty files will suffice.

To add the now edited documentation to the GDExtension and let the editor load it,
you need to add the following lines to your SConstruct file:
Now that you have XML files containing your documentation, the next step is to include them in your GDExtension binary.
Assuming you are using SCons as your build system, you can add the following lines to your ``SConstruct`` file. If you
are using `godot-cpp-template <https://github.com/godotengine/godot-cpp-template>`__, your file already contains code
for this.

.. code-block:: py

if env["target"] in ["editor", "template_debug"]:
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.")
doc_data = env.GodotCPPDocData("src/gen/doc_data.gen.cpp", source=Glob("doc_classes/*.xml"))
sources.append(doc_data)

The if-statement checks if we are compiling the GDExtension library with the ``editor`` and ``template_debug``
flags. SCons then tries to load all the XML files inside the ``doc_classes`` directory and appends them
to the ``sources`` variable which already includes all the source files of your extension. If it fails
it means we are currently trying to compile the library when the ``godot_cpp`` is set to a version before 4.3.
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 +43 to +45
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.


After loading the extension in a 4.3 Godot editor or later and open the documentation of your extension class
either by :kbd:`Ctrl + Click` in the script editor or the Editor help dialog you will see something like this:
After building, launch your ``demo`` project again. You can open the documentation of one of your extension
classes either using :kbd:`Ctrl + Click` on a class name in the script editor, or inside by finding it in the Editor
help dialog. If everything went well, you should see something like this:

.. 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 •
edited
Loading

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.

---------------------

To style specific parts of text you can use BBCode tags similarly to how they can be used in :ref:`RichTextLabels <doc_bbcode_in_richtextlabel>`.
You can set text as bold, italic, underlined, colored, codeblocks etc. by embedding them in tags like this:

.. code-block:: none

[b]this text will be shown as bold[/b]

Currently, the supported tags for the GDExtension documentation system are:

.. list-table::
:class: wrap-normal
:width: 100%
:widths: 60 40

* - Tag
- Example

* - | **b**
| Makes ``{text}`` use the bold (or bold italics) font of ``RichTextLabel``.

- ``[b]{text}[/b]``

* - | **i**
| Makes ``{text}`` use the italics (or bold italics) font of ``RichTextLabel``.

- ``[i]{text}[/i]``

* - | **u**
| Makes ``{text}`` underlined.

- ``[u]{text}[/u]``

* - | **s**
| Makes ``{text}`` strikethrough.

- ``[s]{text}[/s]``

* - | **kbd**
| Makes ``{text}`` use a grey beveled background, indicating a keyboard shortcut.

- ``[kbd]{text}[/kbd]``

* - | **code**
| Makes inline ``{text}`` use the mono font and styles the text color and background like code.

- ``[code]{text}[/code]``

* - | **codeblocks**
| Makes multiline ``{text}`` use the mono font and styles the text color and background like code.
| The addition of the ``[gdscript]`` tag highlights the GDScript specific syntax.

- | ``[codeblocks]``
| ``[gdscript]``
| ``{text}``
| ``[/gdscript]``
| ``[/codeblocks]``

* - | **center**
| Makes ``{text}`` horizontally centered.
| Same as ``[p align=center]``.

- ``[center]{text}[/center]``

* - | **url**
| Creates a hyperlink (underlined and clickable text). Can contain optional ``{text}`` or display ``{link}`` as is.

- | ``[url]{link}[/url]``
| ``[url={link}]{text}[/url]``

* - | **img**
| Inserts an image from the ``{path}`` (can be any valid :ref:`class_Texture2D` resource).
| If ``{width}`` is provided, the image will try to fit that width maintaining
the aspect ratio.
| If both ``{width}`` and ``{height}`` are provided, the image will be scaled
to that size.
| Add ``%`` to the end of ``{width}`` or ``{height}`` value to specify it as percentages of the control width instead of pixels.
| If ``{valign}`` configuration is provided, the image will try to align to the
surrounding text, see :ref:`doc_bbcode_in_richtextlabel_image_and_table_alignment`.
| Supports configuration options, see :ref:`doc_bbcode_in_richtextlabel_image_options`.

- | ``[img]{path}[/img]``
| ``[img={width}]{path}[/img]``
| ``[img={width}x{height}]{path}[/img]``
| ``[img={valign}]{path}[/img]``
| ``[img {options}]{path}[/img]``

* - | **color**
| Changes the color of ``{text}``. Color must be provided by a common name (see
:ref:`doc_bbcode_in_richtextlabel_named_colors`) or using the HEX format (e.g.
``#ff00ff``, see :ref:`doc_bbcode_in_richtextlabel_hex_colors`).
Writing and styling documentation
---------------------------------

- ``[color={code/name}]{text}[/color]``
The format of the class reference XML files is the same as the one used by Godot. Is is documented in
:ref:`doc_class_reference_primer`.

If you are looking for pointers to write high quality documentation, feel free to refer to Godot's
`documentation guidelines <https://contributing.godotengine.org/en/latest/documentation/guidelines/index.html>`__.

Publishing documentation online
-------------------------------

You may want to publish an online reference for your GDExtension, similar to this website.
The most important step is to build reStructuredText (``.rst``) files from your XML class reference:

.. code-block:: bash
.. code-block:: shell

# You need a version.py file, so download it first.
curl -sSLO https://raw.githubusercontent.com/godotengine/godot/refs/heads/master/version.py
Expand All @@ -190,7 +77,10 @@ The most important step is to build reStructuredText (``.rst``) files from your
Your ``.rst`` files will now be available in ``docs/classes/``. From here, you can use
any documentation builder that supports reStructuredText syntax to create a website from them.

`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.
`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 +81 to +83
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.


1. Add `godot-docs <https://github.com/godotengine/godot-docs>`_ as a submodule to your ``docs/`` folder.
2. Copy over its ``conf.py``, ``index.rst``, ``.readthedocs.yaml`` files into ``/docs/``. You may later decide to copy over and edit more of godot-docs' files, like ``_templates/layout.html``.
Expand Down
Loading