From 882e2d8dd605a553d451688c08aa351a3674d175 Mon Sep 17 00:00:00 2001 From: Lukas Tenbrink Date: Wed, 24 Sep 2025 13:46:14 +0200 Subject: [PATCH] Simplify the "Adding documentation" article for godot-cpp, and de-duplicate information. --- .../scripting/cpp/gdextension_docs_system.rst | 186 ++++-------------- 1 file changed, 38 insertions(+), 148 deletions(-) diff --git a/tutorials/scripting/cpp/gdextension_docs_system.rst b/tutorials/scripting/cpp/gdextension_docs_system.rst index 40bf3c683f9..0c1b0e0d6a5 100644 --- a/tutorials/scripting/cpp/gdextension_docs_system.rst +++ b/tutorials/scripting/cpp/gdextension_docs_system.rst @@ -5,172 +5,59 @@ 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 ` (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 +installed and working. If you are using `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 ` - 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 `__, 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. -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 ---------------------- - -To style specific parts of text you can use BBCode tags similarly to how they can be used in :ref:`RichTextLabels `. -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 `__. Publishing documentation online ------------------------------- @@ -178,7 +65,7 @@ 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 @@ -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 `_ uses `Sphinx `_. 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 `_ uses `Sphinx `_. +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 `_ 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``.