From 44dfb3a3908dfed859017d351f3380a1950e39d9 Mon Sep 17 00:00:00 2001
From: Adam Scott <ascott.ca@gmail.com>
Date: Sun, 27 Oct 2024 16:18:36 -0400
Subject: [PATCH] Add filenames as captions for code blocks

---
 .../development/code_style_guidelines.rst     |  2 ++
 .../introduction_to_the_buildsystem.rst       |  6 ++--
 .../compiling/optimizing_for_size.rst         |  3 +-
 .../configuring_an_ide/visual_studio_code.rst |  2 ++
 .../binding_to_external_libraries.rst         | 25 ++++++---------
 .../core_and_modules/custom_audiostreams.rst  | 14 ++++-----
 .../core_and_modules/custom_godot_servers.rst | 22 ++++++-------
 .../custom_modules_in_cpp.rst                 | 31 +++++++------------
 .../custom_resource_format_loaders.rst        | 24 +++++---------
 .../handling_compatibility_breakages.rst      |  3 ++
 tutorials/rendering/compositor.rst            |  5 +--
 .../gdextension/gdextension_cpp_example.rst   |  4 +++
 12 files changed, 64 insertions(+), 77 deletions(-)

diff --git a/contributing/development/code_style_guidelines.rst b/contributing/development/code_style_guidelines.rst
index 9b475cbbf..e55130949 100644
--- a/contributing/development/code_style_guidelines.rst
+++ b/contributing/development/code_style_guidelines.rst
@@ -169,6 +169,7 @@ ones, the following rules should be followed:
 Example:
 
 .. code-block:: cpp
+    :caption: my_new_file.h
 
     /**************************************************************************/
     /*  my_new_file.h                                                         */
@@ -214,6 +215,7 @@ Example:
     #endif // MY_NEW_FILE_H
 
 .. code-block:: cpp
+    :caption: my_new_file.cpp
 
     /**************************************************************************/
     /*  my_new_file.cpp                                                       */
diff --git a/contributing/development/compiling/introduction_to_the_buildsystem.rst b/contributing/development/compiling/introduction_to_the_buildsystem.rst
index 47f9f254f..2a5cef910 100644
--- a/contributing/development/compiling/introduction_to_the_buildsystem.rst
+++ b/contributing/development/compiling/introduction_to_the_buildsystem.rst
@@ -321,8 +321,7 @@ The default ``custom.py`` file can be created at the root of the Godot Engine
 source to initialize any SCons build options passed via the command line:
 
 .. code-block:: python
-
-    # custom.py
+    :caption: custom.py
 
     optimize = "size"
     module_mono_enabled = "yes"
@@ -352,8 +351,7 @@ line option, both overriding the default build configuration:
 It's also possible to override the options conditionally:
 
 .. code-block:: python
-
-    # custom.py
+    :caption: custom.py
 
     import version
 
diff --git a/contributing/development/compiling/optimizing_for_size.rst b/contributing/development/compiling/optimizing_for_size.rst
index 3fac49a65..278f98d49 100644
--- a/contributing/development/compiling/optimizing_for_size.rst
+++ b/contributing/development/compiling/optimizing_for_size.rst
@@ -226,8 +226,7 @@ Alternatively, you can supply a list of disabled modules by creating
 following:
 
 .. code-block:: python
-
-    # custom.py
+    :caption: custom.py
 
     module_basis_universal_enabled = "no"
     module_bmp_enabled = "no"
diff --git a/contributing/development/configuring_an_ide/visual_studio_code.rst b/contributing/development/configuring_an_ide/visual_studio_code.rst
index 2c40ede2e..5141e4b10 100644
--- a/contributing/development/configuring_an_ide/visual_studio_code.rst
+++ b/contributing/development/configuring_an_ide/visual_studio_code.rst
@@ -36,6 +36,7 @@ Importing the project
 - Within the ``tasks.json`` file find the ``"tasks"`` array and add a new section to it:
 
   .. code-block:: js
+    :caption: .vscode/tasks.json
 
     {
       "label": "build",
@@ -199,6 +200,7 @@ To fix include errors you may be having, you need to configure some settings in
 - The ``c_cpp_properties.json`` file should look similar to this for Windows:
 
   .. code-block:: js
+    :caption: .vscode/c_cpp_properties.json
 
     {
       "configurations": [
diff --git a/contributing/development/core_and_modules/binding_to_external_libraries.rst b/contributing/development/core_and_modules/binding_to_external_libraries.rst
index 1276b0cca..e5c9ef139 100644
--- a/contributing/development/core_and_modules/binding_to_external_libraries.rst
+++ b/contributing/development/core_and_modules/binding_to_external_libraries.rst
@@ -20,8 +20,7 @@ To bind to an external library, set up a module directory similar to the Summato
 Next, you will create a header file with a TTS class:
 
 .. code-block:: cpp
-
-    /* tts.h */
+    :caption: godot/modules/tts/tts.h
 
     #ifndef GODOT_TTS_H
     #define GODOT_TTS_H
@@ -45,8 +44,7 @@ Next, you will create a header file with a TTS class:
 And then you'll add the cpp file.
 
 .. code-block:: cpp
-
-    /* tts.cpp */
+    :caption: godot/modules/tts/tts.cpp
 
     #include "tts.h"
 
@@ -82,16 +80,14 @@ need to be created:
 These files should contain the following:
 
 .. code-block:: cpp
-
-    /* register_types.h */
+    :caption: godot/modules/tts/register_types.h
 
     void initialize_tts_module(ModuleInitializationLevel p_level);
     void uninitialize_tts_module(ModuleInitializationLevel p_level);
     /* yes, the word in the middle must be the same as the module folder name */
 
 .. code-block:: cpp
-
-    /* register_types.cpp */
+    :caption: godot/modules/tts/register_types.cpp
 
     #include "register_types.h"
 
@@ -113,8 +109,7 @@ Next, you need to create an ``SCsub`` file so the build system compiles
 this module:
 
 .. code-block:: python
-
-    # SCsub
+    :caption: godot/modules/tts/SCsub
 
     Import('env')
 
@@ -127,9 +122,9 @@ installation commands for Linux below, for reference.
 
 .. code-block:: shell
 
-    sudo apt-get install festival festival-dev <-- Installs festival and speech_tools libraries
-    apt-cache search festvox-* <-- Displays list of voice packages
-    sudo apt-get install festvox-don festvox-rablpc16k festvox-kallpc16k festvox-kdlpc16k <-- Installs voices
+    sudo apt-get install festival festival-dev  # Installs festival and speech_tools libraries
+    apt-cache search festvox-*  # Displays list of voice packages
+    sudo apt-get install festvox-don festvox-rablpc16k festvox-kallpc16k festvox-kdlpc16k  # Installs voices
 
 .. important::
     The voices that Festival uses (and any other potential external/3rd-party
@@ -165,6 +160,7 @@ To add include directories for the compiler to look at you can append it to the
 environment's paths:
 
 .. code-block:: python
+    :caption: godot/modules/tts/SCsub
 
     # These paths are relative to /modules/tts/
     env_tts.Append(CPPPATH=["speech_tools/include", "festival/src/include"])
@@ -186,8 +182,7 @@ If you want to add custom compiler flags when building your module, you need to
 Example `SCsub` with custom flags:
 
 .. code-block:: python
-
-    # SCsub
+    :caption: godot/modules/tts/SCsub
 
     Import('env')
 
diff --git a/contributing/development/core_and_modules/custom_audiostreams.rst b/contributing/development/core_and_modules/custom_audiostreams.rst
index 0f047de9b..888707e90 100644
--- a/contributing/development/core_and_modules/custom_audiostreams.rst
+++ b/contributing/development/core_and_modules/custom_audiostreams.rst
@@ -46,8 +46,7 @@ object regardless how many times ``load`` is called on a specific resource.
 Therefore, playback state must be self-contained in AudioStreamPlayback.
 
 .. code-block:: cpp
-
-    /* audiostream_mytone.h */
+    :caption: audiostream_mytone.h
 
     #include "core/reference.h"
     #include "core/resource.h"
@@ -77,8 +76,7 @@ Therefore, playback state must be self-contained in AudioStreamPlayback.
     };
 
 .. code-block:: cpp
-
-    /* audiostream_mytone.cpp */
+    :caption: audiostream_mytone.cpp
 
     #include "audiostream_mytone.h"
 
@@ -127,8 +125,7 @@ AudioStreamPlayer uses ``mix`` callback to obtain PCM data. The callback must ma
 Since AudioStreamPlayback is controlled by the audio thread, i/o and dynamic memory allocation are forbidden.
 
 .. code-block:: cpp
-
-    /*  audiostreamplayer_mytone.h */
+    :caption: audiostreamplayer_mytone.h
 
     #include "core/reference.h"
     #include "core/resource.h"
@@ -165,8 +162,7 @@ Since AudioStreamPlayback is controlled by the audio thread, i/o and dynamic mem
     };
 
 .. code-block:: cpp
-
-    /* audiostreamplayer_mytone.cpp */
+    :caption: audiostreamplayer_mytone.cpp
 
     #include "audiostreamplayer_mytone.h"
 
@@ -239,6 +235,7 @@ Instead of overloading ``mix``, AudioStreamPlaybackResampled uses ``_mix_interna
 query AudioFrames and ``get_stream_sampling_rate`` to query current mix rate.
 
 .. code-block:: cpp
+    :caption: mytone_audiostream_resampled.h
 
     #include "core/reference.h"
     #include "core/resource.h"
@@ -280,6 +277,7 @@ query AudioFrames and ``get_stream_sampling_rate`` to query current mix rate.
     };
 
 .. code-block:: cpp
+    :caption: mytone_audiostream_resampled.cpp
 
     #include "mytone_audiostream_resampled.h"
 
diff --git a/contributing/development/core_and_modules/custom_godot_servers.rst b/contributing/development/core_and_modules/custom_godot_servers.rst
index 0158092b0..f88cfbffe 100644
--- a/contributing/development/core_and_modules/custom_godot_servers.rst
+++ b/contributing/development/core_and_modules/custom_godot_servers.rst
@@ -39,6 +39,7 @@ At minimum, a server must have a static instance, a sleep timer, a thread loop,
 an initialization state and a cleanup procedure.
 
 .. code-block:: cpp
+    :caption: hilbert_hotel.h
 
     #ifndef HILBERT_HOTEL_H
     #define HILBERT_HOTEL_H
@@ -93,6 +94,7 @@ an initialization state and a cleanup procedure.
     #endif
 
 .. code-block:: cpp
+    :caption: hilbert_hotel.cpp
 
     #include "hilbert_hotel.h"
 
@@ -235,8 +237,7 @@ an initialization state and a cleanup procedure.
     }
 
 .. code-block:: cpp
-
-    /* prime_225.h */
+    :caption: prime_255.h
 
     const uint64_t PRIME[225] = {
             2,3,5,7,11,13,17,19,23,
@@ -275,6 +276,7 @@ RID_Owner maintains a list of RIDs. In practice, RIDs are similar to writing
 object-oriented C code.
 
 .. code-block:: cpp
+    :caption: infinite_bus.h
 
     class InfiniteBus : public RID_Data {
         RID self;
@@ -329,8 +331,14 @@ In ``register_server_types()``, ``Engine::get_singleton()->add_singleton``
 is used to register the dummy class in GDScript.
 
 .. code-block:: cpp
+    :caption: register_types.h
 
-    /* register_types.cpp */
+    /* Yes, the word in the middle must be the same as the module folder name */
+    void register_hilbert_hotel_types();
+    void unregister_hilbert_hotel_types();
+
+.. code-block:: cpp
+    :caption: register_types.cpp
 
     #include "register_types.h"
 
@@ -361,14 +369,6 @@ is used to register the dummy class in GDScript.
         }
     }
 
-.. code-block:: cpp
-
-    /* register_types.h */
-
-    /* Yes, the word in the middle must be the same as the module folder name */
-    void register_hilbert_hotel_types();
-    void unregister_hilbert_hotel_types();
-
 - `servers/register_server_types.cpp <https://github.com/godotengine/godot/blob/master/servers/register_server_types.cpp>`__
 
 Bind methods
diff --git a/contributing/development/core_and_modules/custom_modules_in_cpp.rst b/contributing/development/core_and_modules/custom_modules_in_cpp.rst
index 3d3362e33..31ba1ee77 100644
--- a/contributing/development/core_and_modules/custom_modules_in_cpp.rst
+++ b/contributing/development/core_and_modules/custom_modules_in_cpp.rst
@@ -45,8 +45,7 @@ The example module will be called "summator" (``godot/modules/summator``).
 Inside we will create a summator class:
 
 .. code-block:: cpp
-
-    /* summator.h */
+    :caption: godot/modules/summator/summator.h
 
     #ifndef SUMMATOR_H
     #define SUMMATOR_H
@@ -74,8 +73,7 @@ Inside we will create a summator class:
 And then the cpp file.
 
 .. code-block:: cpp
-
-    /* summator.cpp */
+    :caption: godot/modules/summator/summator.cpp
 
     #include "summator.h"
 
@@ -116,8 +114,7 @@ need to be created:
 These files should contain the following:
 
 .. code-block:: cpp
-
-    /* register_types.h */
+    :caption: godot/modules/summator/register_types.h
 
     #include "modules/register_module_types.h"
 
@@ -126,8 +123,7 @@ These files should contain the following:
     /* yes, the word in the middle must be the same as the module folder name */
 
 .. code-block:: cpp
-
-    /* register_types.cpp */
+    :caption: godot/modules/summator/register_types.cpp
 
     #include "register_types.h"
 
@@ -152,6 +148,7 @@ Next, we need to create an ``SCsub`` file so the build system compiles
 this module:
 
 .. code-block:: python
+    :caption: godot/modules/summator/SCsub
 
     # SCsub
 
@@ -184,8 +181,7 @@ If you want to add custom compiler flags when building your module, you need to
 Example ``SCsub`` with custom flags:
 
 .. code-block:: python
-
-    # SCsub
+    :caption: godot/modules/summator/SCsub
 
     Import('env')
 
@@ -201,6 +197,7 @@ And finally, the configuration file for the module, this is a
 Python script that must be named ``config.py``:
 
 .. code-block:: python
+    :caption: godot/modules/summator/config.py
 
     # config.py
 
@@ -354,8 +351,7 @@ method which will be called before anything else during the
 We now need to add this method to ``register_types`` header and source files:
 
 .. code-block:: cpp
-
-    /* register_types.h */
+    :caption: godot/modules/summator/register_types.h
 
     #define MODULE_SUMMATOR_HAS_PREREGISTER
     void preregister_summator_types();
@@ -369,8 +365,7 @@ We now need to add this method to ``register_types`` header and source files:
           has to be converted to uppercase as well.
 
 .. code-block:: cpp
-
-    /* register_types.cpp */
+    :caption: godot/modules/summator/register_types.cpp
 
     #include "register_types.h"
 
@@ -413,8 +408,7 @@ The solution to avoid such a cost is to build our own module as a shared
 library that will be dynamically loaded when starting our game's binary.
 
 .. code-block:: python
-
-    # SCsub
+    :caption: godot/modules/summator/SCsub
 
     Import('env')
 
@@ -470,8 +464,7 @@ module as shared library (for development) or as a part of the Godot binary
 using the ``ARGUMENT`` command:
 
 .. code-block:: python
-
-    # SCsub
+    :caption: godot/modules/summator/SCsub
 
     Import('env')
 
@@ -626,8 +619,8 @@ The procedure is the following:
 3. Write some test cases. Here's an example:
 
 .. code-block:: cpp
+    :caption: godot/modules/summator/tests/test_summator.h
 
-    // test_summator.h
     #ifndef TEST_SUMMATOR_H
     #define TEST_SUMMATOR_H
 
diff --git a/contributing/development/core_and_modules/custom_resource_format_loaders.rst b/contributing/development/core_and_modules/custom_resource_format_loaders.rst
index 9066fbdb6..add1a045a 100644
--- a/contributing/development/core_and_modules/custom_resource_format_loaders.rst
+++ b/contributing/development/core_and_modules/custom_resource_format_loaders.rst
@@ -56,8 +56,7 @@ read and handle data serialization.
 
 
 .. code-block:: cpp
-
-    /* resource_loader_json.h */
+    :caption: resource_loader_json.h
 
     #ifndef RESOURCE_LOADER_JSON_H
     #define RESOURCE_LOADER_JSON_H
@@ -75,8 +74,7 @@ read and handle data serialization.
     #endif // RESOURCE_LOADER_JSON_H
 
 .. code-block:: cpp
-
-    /* resource_loader_json.cpp */
+    :caption: resource_loader_json.cpp
 
     #include "resource_loader_json.h"
 
@@ -112,8 +110,7 @@ If you'd like to be able to edit and save a resource, you can implement a
 ``ResourceFormatSaver``:
 
 .. code-block:: cpp
-
-    /* resource_saver_json.h */
+    :caption: resource_saver_json.h
 
     #ifndef RESOURCE_SAVER_JSON_H
     #define RESOURCE_SAVER_JSON_H
@@ -130,8 +127,7 @@ If you'd like to be able to edit and save a resource, you can implement a
     #endif // RESOURCE_SAVER_JSON_H
 
 .. code-block:: cpp
-
-    /* resource_saver_json.cpp */
+    :caption: resource_saver_json.cpp
 
     #include "resource_saver_json.h"
 
@@ -164,8 +160,7 @@ understand additional binary formats such as machine learning models.
 Here is an example of creating a custom datatype:
 
 .. code-block:: cpp
-
-    /* resource_json.h */
+    :caption: resource_json.h
 
     #ifndef RESOURCE_JSON_H
     #define RESOURCE_JSON_H
@@ -197,8 +192,7 @@ Here is an example of creating a custom datatype:
     #endif // RESOURCE_JSON_H
 
 .. code-block:: cpp
-
-    /* resource_json.cpp */
+    :caption: resource_json.cpp
 
     #include "resource_json.h"
 
@@ -314,15 +308,13 @@ handler. The handler selects the proper loader automatically
 when ``load`` is called.
 
 .. code-block:: cpp
-
-    /* register_types.h */
+    :caption: register_types.h
 
     void register_json_types();
     void unregister_json_types();
 
 .. code-block:: cpp
-
-    /* register_types.cpp */
+    :caption: register_types.cpp
 
     #include "register_types.h"
 
diff --git a/contributing/development/handling_compatibility_breakages.rst b/contributing/development/handling_compatibility_breakages.rst
index 3c2ed2e25..23407e19f 100644
--- a/contributing/development/handling_compatibility_breakages.rst
+++ b/contributing/development/handling_compatibility_breakages.rst
@@ -49,6 +49,7 @@ that introduced the change (``88047`` in this example). These compatibility meth
 like ``core/math/a_star_grid_2d.compat.inc`` in this case:
 
 .. code-block:: cpp
+    :caption: core/math/a_star_grid_2d.compat.inc
 
     /**************************************************************************/
     /*  a_star_grid_2d.compat.inc                                             */
@@ -106,6 +107,7 @@ This file should always be placed next to the original file, and have ``.compat.
 Next, this should be included in the ``.cpp`` file we're adding compatibility methods to, so ``core/math/a_star_grid_2d.cpp``:
 
 .. code-block:: cpp
+    :caption: core/math/a_star_grid_2d.cpp
 
     #include "a_star_grid_2d.h"
     #include "a_star_grid_2d.compat.inc"
@@ -117,6 +119,7 @@ done during the development of 4.3, this would be ``misc/extension_api_validatio
 this example):
 
 .. code-block:: text
+    :caption: misc/extension_api_validation/4.2-stable.expected
 
     GH-88047
     --------
diff --git a/tutorials/rendering/compositor.rst b/tutorials/rendering/compositor.rst
index 763a9a2ab..42dc228ad 100644
--- a/tutorials/rendering/compositor.rst
+++ b/tutorials/rendering/compositor.rst
@@ -45,6 +45,7 @@ We need to extend our node from :ref:`CompositorEffect <class_CompositorEffect>`
 We must also give our script a class name.
 
 .. code-block:: gdscript
+    :caption: post_process_shader.gd
 
     @tool
     extends CompositorEffect
@@ -120,7 +121,7 @@ and thus runs within our rendering thread.
 
 We need to ensure that we set our new shader code, and mark our
 shader code as dirty, without our render thread accessing this
-data at the same time. 
+data at the same time.
 
 Next we initialize our effect.
 
@@ -254,7 +255,7 @@ this at the right stage of rendering.
                 if size.x == 0 and size.y == 0:
                     return
 
-                # We can use a compute shader here 
+                # We can use a compute shader here
                 var x_groups = (size.x - 1) / 8 + 1
                 var y_groups = (size.y - 1) / 8 + 1
                 var z_groups = 1
diff --git a/tutorials/scripting/gdextension/gdextension_cpp_example.rst b/tutorials/scripting/gdextension/gdextension_cpp_example.rst
index a16285185..0440b3d32 100644
--- a/tutorials/scripting/gdextension/gdextension_cpp_example.rst
+++ b/tutorials/scripting/gdextension/gdextension_cpp_example.rst
@@ -161,6 +161,7 @@ In the ``src`` folder, we'll start with creating our header file for the
 GDExtension node we'll be creating. We will name it ``gdexample.h``:
 
 .. code-block:: cpp
+    :caption: gdextension_cpp_example/src/gdexample.h
 
     #ifndef GDEXAMPLE_H
     #define GDEXAMPLE_H
@@ -214,6 +215,7 @@ as the ``_process`` function you're used to in GDScript.
 Let's implement our functions by creating our ``gdexample.cpp`` file:
 
 .. code-block:: cpp
+    :caption: gdextension_cpp_example/src/gdexample.cpp
 
     #include "gdexample.h"
     #include <godot_cpp/core/class_db.hpp>
@@ -253,6 +255,7 @@ is a small bit of code that tells Godot about all the classes in our
 GDExtension plugin.
 
 .. code-block:: cpp
+    :caption: gdextension_cpp_example/src/register_types.cpp
 
     #include "register_types.h"
 
@@ -306,6 +309,7 @@ At last, we need the header file for the ``register_types.cpp`` named
 ``register_types.h``.
 
 .. code-block:: cpp
+    :caption: gdextension_cpp_example/src/register_types.h
 
     #ifndef GDEXAMPLE_REGISTER_TYPES_H
     #define GDEXAMPLE_REGISTER_TYPES_H