Add a page for GDExtension's extension_api.json files

engine_details/development/handling_compatibility_breakages.rst

@@ -123,8 +123,9 @@ then run it with the ``--dump-extension-api`` flag:
     scons
     godot --dump-extension-api
 
-This will create a file named ``extension_api.json`` in your current directory. Switch to your feature branch, recompile Godot,
-and then run it with the ``--validate-extension-api`` flag followed by the path to the ``extension_api.json`` file you just generated:
+This will create a file named :ref:`extension_api.json <doc_gdextension_api_file>` in your current directory.
+Switch to your feature branch, recompile Godot, and then run it with the ``--validate-extension-api`` flag followed by
+the path to the ``extension_api.json`` file you just generated:
 
 .. code-block:: shell
 

tutorials/scripting/cpp/about_godot_cpp.rst

@@ -65,25 +65,13 @@ godot-cpp (or another GDExtension system) isn't enough:
 Version compatibility
 ---------------------
 
+.. seealso::
+
+    See :ref:`GDExtension version compatibility <doc_what_is_gdextension_version_compatibility>` for more details.
+
 GDExtensions targeting an earlier version of Godot should 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.
-
-There is one exception to this: extensions targeting Godot 4.0 will **not** work with
-Godot 4.1 and later (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. You can learn more about the process of using custom
-``extension_api.json`` files in the :ref:`build system section <doc_godot_cpp_build_system>`.
+If you're using a custom version of Godot, you should also generate a custom :ref:`extension_api.json <doc_gdextension_api_file>`
+for your GDExtension. You can learn about the process in the :ref:`build system section <doc_godot_cpp_build_system>`.

tutorials/scripting/cpp/build_system/scons.rst

@@ -77,8 +77,8 @@ for a GitHub based CI workflow.
 Using a custom API file
 -----------------------
 
-Every branch of godot-cpp comes with an API file (``extension_api.json``) appropriate for
-the respective Godot version (e.g. the ``4.3`` branch comes with the API file compatible
+Every branch of godot-cpp comes with an API file (:ref:`extension_api.json <doc_gdextension_api_file>`)
+appropriate for the respective Godot version (e.g. the ``4.3`` branch comes with the API file compatible
 with Godot version ``4.3`` and later).
 
 However, you may want to use a custom ``extension_api.json``, for example:

tutorials/scripting/gdextension/extension_api_file.rst

@@ -0,0 +1,31 @@
+.. _doc_gdextension_api_file:
+
+The GDExtension API file
+========================
+
+The ``extension_api.json`` is a file that contains information about all the high level
+APIs that are exposed from Godot for use in programming languages like GDScript or C++.
+
+You can use the Godot executable to dump the file by using the following command:
+
+.. code-block:: shell
+
+    godot --dump-extension-api
+
+This file is intended to be used by GDExtension language bindings to generate code for
+using this API in whatever form makes the most sense for that language.
+
+.. note::
+
+    This is not to be confused with the ``gdextension_interface.json`` file, which
+    is also used by GDExtension language bindings. ``gdextension_interface.json``
+    is more low level, and is used to establish communication between Godot and a
+    GDExtension, while ``gdextension_interface.json`` contains high level APIs.
+
+The goal of this page is to explain the JSON format for the GDExtension language bindings that
+would like to do their own code generation from the JSON.
+
+Overall structure
+-----------------
+
+TBD

tutorials/scripting/gdextension/gdextension_c_example.rst

@@ -64,7 +64,7 @@ To get this JSON file, just call the Godot executable:
 
     godot --dump-extension-api
 
-The resulting ``extension_api.json`` file will be created in the current
+The resulting :ref:`extension_api.json <doc_gdextension_api_file>` file will be created in the current
 folder. You can copy this file to the example folder to have it handy.
 
 .. note::

tutorials/scripting/gdextension/gdextension_interface_json_file.rst

@@ -17,10 +17,10 @@ using this API in whatever form makes the most sense for that language.
 
 .. note::
 
-    This is not to be confused with the ``extension_api.json``, which is also used by
-    GDExtension language bindings, and contains information about the classes and
-    methods that are exposed by Godot. The ``gdextension_interface.json`` is more
-    low-level, and is used to interact with those higher-level classes and methods.
+    This is not to be confused with the :ref:`extension_api.json <doc_gdextension_api_file`,
+    which is also used by GDExtension language bindings, and contains information about the
+    classes and methods that are exposed by Godot. The ``gdextension_interface.json`` is
+    more low-level, and is used to interact with those higher-level classes and methods.
 
 For languages that can be extended via C, or provide tools for interacting with C code,
 it's also possible to use the Godot executable to dump a generated C header file:

tutorials/scripting/gdextension/index.rst

@@ -24,4 +24,5 @@ articles instead, such as the articles about :ref:`C++ (godot-cpp) <doc_godot_cp
    what_is_gdextension
    gdextension_file
    gdextension_interface_json_file
+   extension_api_file
    gdextension_c_example

tutorials/scripting/gdextension/what_is_gdextension.rst

@@ -9,8 +9,8 @@ at runtime. You can use it to run native code without compiling it with the engi
 
 There are three primary methods with which this is achieved:
 
-* ``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_interface.h <doc_gdextension_interface_json_file>`: A set of C functions that Godot and a GDExtension can use to communicate.
+* :ref:`extension_api.json <doc_gdextension_api_file>`: 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.
 
 Most people create GDExtensions with some existing language binding, such as :ref:`godot-cpp (for C++) <doc_godot_cpp>`,
@@ -19,4 +19,29 @@ or one of the :ref:`community-made ones <doc_what_is_gdnative_third_party_bindin
 Version compatibility
 ---------------------
 
-See :ref:`godot-cpp Version Compatibility <doc_what_is_gdextension_version_compatibility>`, which applies to all GDExtensions.
+GDExtensions targeting an earlier version of Godot should 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.
+
+There is one exception to this: extensions targeting Godot 4.0 will **not** work with
+Godot 4.1 and later (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 :ref:`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
+:ref:`extension_api.json <doc_gdextension_api_file>` from it for your GDExtensions,
+because it may have some differences from official Godot builds. This can be accomplished
+using the Godot executable:
+
+.. code-block:: shell
+
+    godot --dump-extension-api