Merge pull request #10151 from adamscott/add-caption-filename

Add filenames as captions for code blocks

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                                                       */

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
 

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"

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": [

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')
 

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"
 

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

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
 

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"
 

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
     --------

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

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