Split C++ (godot-cpp) and GDExtension system info into separate categories, children of Scripting.

Author: Ivorforce

about/docs_changelog.rst

@@ -84,7 +84,7 @@ GDExtension
 ~~~~~~~~~~~
 
 - :ref:`doc_gdextension_file`
-- :ref:`doc_gdextension_docs_system`
+- :ref:`doc_godot_cpp_docs_system`
 
 Migrating
 ~~~~~~~~~

tutorials/scripting/gdextension/gdextension_c_example.rst

@@ -2162,5 +2162,5 @@ quite straightforward and not very verbose.
 
 If you want to create actual extensions, it is preferred to use the C++ bindings
 instead, as it takes away all of the boilerplate from your code. Check the
-:ref:`GDExtension C++ example <doc_gdextension_cpp_example>` to see how you can
+:ref:`godot-cpp documentation <doc_godot_cpp>` to see how you can
 do this.

tutorials/scripting/gdextension/gdextension_file.rst

@@ -9,7 +9,7 @@ Introduction
 The ``.gdextension`` file in your project contains the instructions for how to load
 the GDExtension. The instructions are separated into specific sections. This page
 should give you a quick overview of the different options available to you. For an introduction
-how to get started with GDExtensions take a look at the :ref:`GDExtension C++ Example <doc_gdextension_cpp_example>`.
+how to get started with C++ (godot-cpp), take a look at the :ref:`GDExtension C++ Example <doc_godot_cpp_getting_started>`.
 
 Configuration section
 ---------------------

tutorials/scripting/gdextension/index.rst

@@ -1,14 +1,26 @@
 :allow_comments: False
 
-GDExtension
-===========
+.. _doc_gdextension:
+
+The GDExtension system
+======================
+
+**GDExtension** is a Godot-specific technology that lets the engine interact with
+native `shared libraries <https://en.wikipedia.org/wiki/Library_(computing)#Shared_libraries>`__
+at runtime. You can use it to run native code without compiling it with the engine.
+
+.. note:: GDExtension is *not* a scripting language and has no relation to
+          :ref:`GDScript <doc_gdscript>`.
+
+This section describes how GDExtension works, and is generally aimed at people wanting to make a GDExtension from
+scratch, for example to create language bindings. If you want to use existing language bindings, please refer to other
+articles instead, such as the articles about :ref:`C++ (godot-cpp) <doc_godot_cpp>` or one of the
+:ref:`community-made ones <doc_what_is_gdnative_third_party_bindings>`.
 
 .. toctree::
    :maxdepth: 1
-   :name: toc-tutorials-gdnative
+   :name: toc-tutorials-gdextension
 
    what_is_gdextension
-   gdextension_cpp_example
-   gdextension_c_example
    gdextension_file
-   gdextension_docs_system
+   gdextension_c_example

tutorials/scripting/gdextension/what_is_gdextension.rst

@@ -3,129 +3,20 @@
 What is GDExtension?
 ====================
 
-Introduction
-------------
-
 **GDExtension** is a Godot-specific technology that lets the engine interact with
 native `shared libraries <https://en.wikipedia.org/wiki/Library_(computing)#Shared_libraries>`__
 at runtime. You can use it to run native code without compiling it with the engine.
 
-.. note:: GDExtension is *not* a scripting language and has no relation to
-          :ref:`GDScript <doc_gdscript>`.
-
-Differences between GDExtension and C++ modules
------------------------------------------------
-
-You can use both GDExtension and :ref:`C++ modules <doc_custom_modules_in_cpp>` to
-run C or C++ code in a Godot project.
-
-They also both allow you to integrate third-party libraries into Godot. The one
-you should choose depends on your needs.
-
-.. warning::
-
-    GDExtension is currently *experimental*, which means that we may
-    break compatibility in order to fix major bugs or include critical features.
-
-Advantages of GDExtension
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Unlike modules, GDExtension doesn't require compiling the engine's source code,
-making it easier to distribute your work. It gives you access to most of the API
-available to GDScript and C#, allowing you to code game logic with full control
-regarding performance. It's ideal if you need high-performance code you'd like
-to distribute as an add-on in the :ref:`asset library <doc_what_is_assetlib>`.
-
-Also:
-
-- GDExtension is not limited to C and C++. Thanks to :ref:`third-party bindings
-  <doc_what_is_gdnative_third_party_bindings>`, you can use it with many other
-  languages.
-- You can use the same compiled GDExtension library in the editor and exported
-  project. With C++ modules, you have to recompile all the export templates you
-  plan to use if you require its functionality at runtime.
-- GDExtension only requires you to compile your library, not the whole engine.
-  That's unlike C++ modules, which are statically compiled into the engine.
-  Every time you change a module, you need to recompile the engine. Even with
-  incremental builds, this process is slower than using GDExtension.
-
-Advantages of C++ modules
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-We recommend :ref:`C++ modules <doc_custom_modules_in_cpp>` in cases where
-GDExtension isn't enough:
-
-- C++ modules provide deeper integration into the engine. GDExtension's access
-  is not as deep as static modules.
-- You can use C++ modules to provide additional features in a project without
-  carrying native library files around. This extends to exported projects.
-
-.. note::
-
-    If you notice that specific systems are not accessible via GDExtension
-    but are via custom modules, feel free to open an issue on the
-    `godot-cpp repository <https://github.com/godotengine/godot-cpp>`__
-    to discuss implementation options for exposing the missing functionality.
+There are three primary methods with which this is achieved:
 
-Supported languages
--------------------
+* ``gdextension_interface.h``: A set of C functions that Godot and a GDExtension can use to communicate.
+* ``extension_api.json``: A list of C functions that are exposed from Godot APIs (:ref:`Core Features <doc_scripting_core_features>`).
+* :ref:``*.gdextension <doc_gdextension_file>`: A file format read by Godot to load a GDExtension.
 
-The Godot developers officially support the following language bindings for
-GDExtension:
-
-- C++ :ref:`(tutorial) <doc_gdextension_cpp_example>`
-
-.. note::
-
-    There are no plans to support additional languages with GDExtension officially.
-    That said, the community offers several bindings for other languages (see
-    below).
-
-.. _doc_what_is_gdnative_third_party_bindings:
-
-The bindings below are developed and maintained by the community:
-
-.. Binding developers: Feel free to open a pull request to add your binding if it's well-developed enough to be used in a project.
-.. Please keep languages sorted in alphabetical order.
-
-- `D <https://github.com/godot-dlang/godot-dlang>`__
-- `Go <https://github.com/grow-graphics/gd>`__
-- `Nim <https://github.com/godot-nim/gdext-nim>`__
-- `Rust <https://github.com/godot-rust/gdext>`__
-- `Swift <https://github.com/migueldeicaza/SwiftGodot>`__
-
-.. note::
-
-    Not all bindings mentioned here may be production-ready. Make sure to
-    research options thoroughly before starting a project with one of those.
-    Also, double-check whether the binding is compatible with the Godot version
-    you're using.
-
-.. _doc_what_is_gdextension_version_compatibility:
+Most people create GDExtensions with some existing language binding, such as :ref:`godot-cpp (for C++) <doc_godot_cpp>`,
+or one of the :ref:`community-made ones <doc_what_is_gdnative_third_party_bindings>`.
 
 Version compatibility
 ---------------------
 
-Usually, GDExtensions targeting an earlier version of Godot will work in later
-minor versions, but not vice-versa. For example, a GDExtension targeting Godot 4.2
-should work just fine in Godot 4.3, but one targeting Godot 4.3 won't work in Godot 4.2.
-
-For this reason, when creating GDExtensions, you may want to target the lowest version of
-Godot that has the features you need, *not* the most recent version of Godot. This can
-save you from needing to create multiple builds for different versions of Godot.
-
-However, GDExtension is currently *experimental*, which means that we may
-break compatibility in order to fix major bugs or include critical features.
-For example, GDExtensions created for Godot 4.0 aren't compatible with Godot
-4.1 (see :ref:`updating_your_gdextension_for_godot_4_1`).
-
-GDExtensions are also only compatible with engine builds that use the same
-level of floating-point precision the extension was compiled for. This means
-that if you use an engine build with double-precision floats, the extension must
-also be compiled for double-precision floats and use an ``extension_api.json``
-file generated by your custom engine build. See :ref:`doc_large_world_coordinates`
-for details.
-
-Generally speaking, if you build a custom version of Godot, you should generate an
-``extension_api.json`` from it for your GDExtensions, because it may have some differences
-from official Godot builds.
+See :ref:`_doc_what_is_gdextension_version_compatibility <godot-cpp Version Compatibility>`, which applies to all GDExtensions.

tutorials/scripting/godot_cpp/about_godot_cpp.rst

@@ -0,0 +1,96 @@
+.. _doc_about_godot_cpp:
+
+About godot-cpp
+===============
+
+`godot-cpp <https://github.com/godotengine/godot-cpp>`__ are the official C++ GDExtension bindings, maintained
+as part of the Godot project.
+
+godot-cpp is built with the :ref:`GDExtension system <doc_gdextension>`, which allows access to Godot in almost the
+same way as :ref:`modules <doc_custom_modules_in_cpp>`: A lot of `engine code <https://github.com/godotengine/godot>`__
+can be used in your godot-cpp project almost exactly as it is.
+
+In particular, godot-cpp has access to all functions that :ref:`GDScript <doc_gdscript>` and :ref:`C# <doc_c_sharp>`
+have, and additional access to a few more for fast low-level access of data, or deeper integration with Godot.
+
+Differences between godot-cpp and C++ modules
+-----------------------------------------------
+
+You can use both `godot-cpp <https://github.com/godotengine/godot-cpp>`__
+and :ref:`C++ modules <doc_custom_modules_in_cpp>` to run C or C++ code in a Godot project.
+
+They also both allow you to integrate third-party libraries into Godot. The one
+you should choose depends on your needs.
+
+.. warning::
+
+    godot-cpp is currently *experimental*, which means that we may
+    break compatibility in order to fix major bugs or include critical features.
+
+
+Advantages of godot-cpp
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Unlike modules, godot-cpp (and GDExtensions, in general) don't require
+compiling the engine's source code, making it easier to distribute your work.
+It gives you access to most of the API available to GDScript and C#, allowing
+you to code game logic with full control regarding performance. It's ideal if
+you need high-performance code you'd like to distribute as an add-on in the
+:ref:`asset library <doc_what_is_assetlib>`.
+
+Also:
+
+- You can use the same compiled godot-cpp library in the editor and exported
+  project. With C++ modules, you have to recompile all the export templates you
+  plan to use if you require its functionality at runtime.
+- godot-cpp only requires you to compile your library, not the whole engine.
+  That's unlike C++ modules, which are statically compiled into the engine.
+  Every time you change a module, you need to recompile the engine. Even with
+  incremental builds, this process is slower than using godot-cpp.
+
+Advantages of C++ modules
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We recommend :ref:`C++ modules <doc_custom_modules_in_cpp>` in cases where
+godot-cpp (or another GDExtension system) isn't enough:
+
+- C++ modules provide deeper integration into the engine. GDExtension's access
+  is not as deep as static modules.
+- You can use C++ modules to provide additional features in a project without
+  carrying native library files around. This extends to exported projects.
+
+.. note::
+
+    If you notice that specific systems are not accessible via godot-cpp
+    but are via custom modules, feel free to open an issue on the
+    `godot-cpp repository <https://github.com/godotengine/godot-cpp>`__
+    to discuss implementation options for exposing the missing functionality.
+
+.. _doc_what_is_gdextension_version_compatibility:
+
+Version compatibility
+---------------------
+
+Usually, GDExtensions targeting an earlier version of Godot will work in later
+minor versions, but not vice-versa. For example, a GDExtension targeting Godot 4.2
+should work just fine in Godot 4.3, but one targeting Godot 4.3 won't work in Godot 4.2.
+
+For this reason, when creating GDExtensions, you may want to target the lowest version of
+Godot that has the features you need, *not* the most recent version of Godot. This can
+save you from needing to create multiple builds for different versions of Godot.
+
+However, GDExtension is currently *experimental*, which means that we may
+break compatibility in order to fix major bugs or include critical features.
+For example, GDExtensions created for Godot 4.0 aren't compatible with Godot
+4.1 (see :ref:`updating_your_gdextension_for_godot_4_1`).
+
+GDExtensions are also only compatible with engine builds that use the same
+level of floating-point precision the extension was compiled for. This means
+that if you use an engine build with double-precision floats, the extension must
+also be compiled for double-precision floats and use an ``extension_api.json``
+file generated by your custom engine build. See :ref:`doc_large_world_coordinates`
+for details.
+
+Generally speaking, if you build a custom version of Godot, you should generate an
+``extension_api.json`` from it for your GDExtensions, because it may have some differences
+from official Godot builds.

tutorials/scripting/gdextension/files/cpp_example/SConstruct renamed to tutorials/scripting/godot_cpp/files/cpp_example/SConstruct

@@ -1,29 +1,38 @@
-.. _doc_gdextension_cpp_example:
+.. _doc_godot_cpp_getting_started:
 
-GDExtension C++ example
-=======================
+Getting started
+===============
 
-Introduction
-------------
+Workflow overview
+-----------------
+
+As a GDExtension, godot-cpp is more complicated to use than :ref:`GDScript <doc_gdscript>` and :ref:`C# <doc_c_sharp>`.
+If you decide to work with it, here's what to expect your workflow to look like:
 
-The C++ bindings for GDExtension are built on top of the C GDExtension API
-and provide a nicer way to "extend" nodes and other built-in classes in Godot using C++.
-This new system allows the extension of Godot to nearly the same
-level as statically linked C++ modules.
+* Create a new godot-cpp project (from the `template <https://github.com/godotengine/godot-cpp-template>`__, or from scratch, as explained below).
+* Develop your code with your :ref:`favorite IDE <toc-devel-configuring_an_ide>` locally.
+* Build and test your code with the earliest compatible Godot version.
+* Create builds for all platforms you want to support (e.g. using `GitHub Actions <https://github.com/godotengine/godot-cpp-template/blob/main/.github/workflows/builds.yml>`__).
+* Optional: Publish on the `Godot Asset Library <https://godotengine.org/asset-library/asset>`__.
 
-You can download the included example in the test folder of the godot-cpp
-repository `on GitHub <https://github.com/godotengine/godot-cpp>`__.
+Example project
+---------------
+
+For your first godot-cpp project, we recommend starting with this guide to understand the technology involved with
+godot-cpp. After you're done, you can use the `godot-cpp template <https://github.com/godotengine/godot-cpp-template>`__,
+which has better coverage of features, such as a GitHub action pipeline and useful ``SConstruct`` boilerplate code.
+However, the template does not explain itself to a high level of detail, which is why we recommend going through this
+guide first.
 
 Setting up the project
 ----------------------
 
 There are a few prerequisites you'll need:
 
-- a Godot 4 executable,
-- a C++ compiler,
-- SCons as a build tool,
-- a copy of the `godot-cpp
-  repository <https://github.com/godotengine/godot-cpp>`__.
+- A Godot 4 executable.
+- A C++ compiler.
+- SCons as a build tool.
+- A copy of the `godot-cpp repository <https://github.com/godotengine/godot-cpp>`__.
 
 See also :ref:`Configuring an IDE <toc-devel-configuring_an_ide>`
 and :ref:`Compiling <toc-devel-compiling>` as the build tools are identical
@@ -719,6 +728,9 @@ Every second, we output our position to the console.
 Next steps
 ----------
 
-We hope the above example showed you the basics. You can
-build upon this example to create full-fledged scripts to control nodes in Godot
-using C++.
+We hope the above example showed you the basics. You can build upon this example to create full-fledged scripts
+to control nodes in Godot using C++!
+
+Instead of basing your project off the above example setup, we recommend to restart now by cloning the
+`godot-cpp template <https://github.com/godotengine/godot-cpp-template>`__, and base your project off of that.
+It has better coverage of features, such as a GitHub build action and additional useful ``SConstruct`` boilerplate.

tutorials/scripting/gdextension/gdextension_cpp_example.rst renamed to tutorials/scripting/godot_cpp/gdextension_cpp_example.rst

@@ -1,7 +1,7 @@
-.. _doc_gdextension_docs_system:
+.. _doc_godot_cpp_docs_system:
 
-GDExtension documentation system
-================================
+Adding documentation
+====================
 
 .. note::
 
@@ -15,7 +15,7 @@ XML files (one per class) to document the exposed constructors, properties, meth
 
 .. note::
 
-    We are assuming you are using the project files explained in the :ref:`GDExtension C++ Example <doc_gdextension_cpp_example>`
+    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

tutorials/scripting/gdextension/gdextension_docs_system.rst renamed to tutorials/scripting/godot_cpp/gdextension_docs_system.rst

@@ -0,0 +1,17 @@
+:allow_comments: False
+
+.. _doc_godot_cpp:
+
+C++ (godot-cpp)
+===============
+
+This section documents `godot-cpp <https://github.com/godotengine/godot-cpp>`__,
+the official C++ GDExtension bindings maintained as part of the Godot project.
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-tutorials-godot-cpp
+
+   about_godot_cpp
+   gdextension_cpp_example
+   gdextension_docs_system