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

Add filenames as captions for code blocks

Author: mhilbrunner

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