Browse Source

Replace uses of shorthand codeblock syntax to avoid issues with localization

Previously, many paragraphs in the documentation used `::` at the end of a line
as a replacement for a single colon (and `::` on the following line).
Due to this, the `::` was part of the extracted string for localization.
Weblate also showed a warning about the trailing `::`, as it's not
normally expected to be there.

This change requires translators to revalidate all modified strings.
However, considering many of those have broken code blocks due to translators
replacing `::` with `:`, it can be a good idea.

This also adds documentation writing guidelines for code blocks and admonitions.
This commit does not modify existing admonitions in any way (as this would
lead to a much larger diff, and require more localizable text to be revalidated
by translators).
Hugo Locurcio 2 months ago
parent
commit
8a6ad4c926
32 changed files with 580 additions and 200 deletions
  1. 3 1
      about/complying_with_licenses.rst
  2. 6 2
      contributing/development/compiling/compiling_for_ios.rst
  3. 12 4
      contributing/development/compiling/compiling_for_linuxbsd.rst
  4. 24 8
      contributing/development/compiling/compiling_for_macos.rst
  5. 24 8
      contributing/development/compiling/compiling_for_web.rst
  6. 30 10
      contributing/development/compiling/compiling_for_windows.rst
  7. 3 1
      contributing/development/compiling/compiling_with_dotnet.rst
  8. 3 1
      contributing/development/compiling/index.rst
  9. 12 4
      contributing/development/compiling/introduction_to_the_buildsystem.rst
  10. 8 4
      contributing/development/core_and_modules/custom_modules_in_cpp.rst
  11. 3 1
      contributing/development/core_and_modules/custom_resource_format_loaders.rst
  12. 3 1
      contributing/development/debugging/macos_debug.rst
  13. 3 1
      contributing/development/debugging/vulkan/vulkan_validation_layers.rst
  14. 6 2
      contributing/documentation/docs_image_guidelines.rst
  15. 54 2
      contributing/documentation/docs_writing_guidelines.rst
  16. 3 1
      contributing/documentation/editor_and_docs_localization.rst
  17. 3 1
      tutorials/assets_pipeline/importing_3d_scenes/import_configuration.rst
  18. 6 2
      tutorials/best_practices/project_organization.rst
  19. 3 1
      tutorials/export/exporting_projects.rst
  20. 3 1
      tutorials/i18n/pseudolocalization.rst
  21. 3 1
      tutorials/io/binary_serialization_api.rst
  22. 3 1
      tutorials/migrating/upgrading_to_godot_4.1.rst
  23. 6 2
      tutorials/physics/physics_introduction.rst
  24. 50 38
      tutorials/platform/android/android_plugin.rst
  25. 3 1
      tutorials/platform/ios/ios_plugin.rst
  26. 12 4
      tutorials/scripting/evaluating_expressions.rst
  27. 159 53
      tutorials/scripting/gdscript/gdscript_basics.rst
  28. 9 3
      tutorials/scripting/gdscript/gdscript_documentation_comments.rst
  29. 18 6
      tutorials/scripting/gdscript/gdscript_exports.rst
  30. 69 23
      tutorials/scripting/gdscript/static_typing.rst
  31. 33 11
      tutorials/shaders/shader_reference/shader_functions.rst
  32. 3 1
      tutorials/ui/bbcode_in_richtextlabel.rst

+ 3 - 1
about/complying_with_licenses.rst

@@ -42,7 +42,9 @@ Requirements
 In the case of the MIT license, the only requirement is to include the license
 text somewhere in your game or derivative project.
 
-This text reads as follows::
+This text reads as follows:
+
+::
 
     This game uses Godot Engine, available under the following license:
 

+ 6 - 2
contributing/development/compiling/compiling_for_ios.rst

@@ -24,7 +24,9 @@ Requirements
    from the `MoltenVK SDK <https://github.com/KhronosGroup/MoltenVK#fetching-moltenvk-source-code>`__.
 
 .. note:: If you have `Homebrew <https://brew.sh/>`_ installed, you can easily
-          install SCons using the following command::
+          install SCons using the following command:
+
+          ::
 
               brew install scons
 
@@ -33,7 +35,9 @@ Requirements
 
           Similarly, if you have `MacPorts <https://www.macports.org/>`_
           installed, you can easily install SCons using the
-          following command::
+          following command:
+
+          ::
 
               sudo port install scons
 

+ 12 - 4
contributing/development/compiling/compiling_for_linuxbsd.rst

@@ -301,11 +301,15 @@ Running a headless/server build
 -------------------------------
 
 To run in *headless* mode which provides editor functionality to export
-projects in an automated manner, use the normal build::
+projects in an automated manner, use the normal build:
+
+::
 
     scons platform=linuxbsd target=editor
 
-And then use the ``--headless`` command line argument::
+And then use the ``--headless`` command line argument:
+
+::
 
     ./bin/godot.linuxbsd.editor.x86_64 --headless
 
@@ -468,7 +472,9 @@ the default GCC + GNU ld setup:
 - Clang tends to give more useful error messages compared to GCC.
 
 To do so, install Clang and the ``lld`` package from your distribution's package manager
-then use the following SCons command::
+then use the following SCons command:
+
+::
 
     scons platform=linuxbsd use_llvm=yes linker=lld
 
@@ -478,7 +484,9 @@ created in the ``bin/`` folder.
 It's still recommended to use GCC for production builds as they can be compiled using
 link-time optimization, making the resulting binaries smaller and faster.
 
-If this error occurs::
+If this error occurs:
+
+::
 
     /usr/bin/ld: cannot find -l:libatomic.a: No such file or directory
 

+ 24 - 8
contributing/development/compiling/compiling_for_macos.rst

@@ -25,7 +25,9 @@ For compiling under macOS, the following is required:
   ``misc/scripts/install_vulkan_sdk_macos.sh`` within the Godot source repository.
 
 .. note:: If you have `Homebrew <https://brew.sh/>`_ installed, you can easily
-          install SCons using the following command::
+          install SCons using the following command:
+
+          ::
 
               brew install scons
 
@@ -34,7 +36,9 @@ For compiling under macOS, the following is required:
 
           Similarly, if you have `MacPorts <https://www.macports.org/>`_
           installed, you can easily install SCons using the
-          following command::
+          following command:
+
+          ::
 
               sudo port install scons
 
@@ -80,7 +84,9 @@ Automatic ``.app`` bundle creation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To automatically create an ``.app`` bundle like in the official builds, use the ``generate_bundle=yes`` option on the *last*
-SCons command used to build editor::
+SCons command used to build editor:
+
+::
 
     scons platform=macos arch=x86_64
     scons platform=macos arch=arm64 generate_bundle=yes
@@ -89,7 +95,9 @@ Manual ``.app`` bundle creation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To support both architectures in a single "Universal 2" binary,
-run the above two commands and then use ``lipo`` to bundle them together::
+run the above two commands and then use ``lipo`` to bundle them together:
+
+::
 
     lipo -create bin/godot.macos.editor.x86_64 bin/godot.macos.editor.arm64 -output bin/godot.macos.editor.universal
 
@@ -117,11 +125,15 @@ Running a headless/server build
 -------------------------------
 
 To run in *headless* mode which provides editor functionality to export
-projects in an automated manner, use the normal build::
+projects in an automated manner, use the normal build:
+
+::
 
     scons platform=macos target=editor
 
-And then use the ``--headless`` command line argument::
+And then use the ``--headless`` command line argument:
+
+::
 
     ./bin/godot.macos.editor.x86_64 --headless
 
@@ -179,7 +191,9 @@ an *Universal 2* binary from two separate ARM64 and x86_64 binaries (if both wer
     MoltenVK without having to recompile export templates.
 
 You can then zip the ``macos_template.app`` folder to reproduce the ``macos.zip``
-template from the official Godot distribution::
+template from the official Godot distribution:
+
+::
 
     zip -r9 macos.zip macos_template.app
 
@@ -208,7 +222,9 @@ repository/extracted the zip), e.g.::
 
     export OSXCROSS_ROOT="$HOME/osxcross"
 
-Now you can compile with SCons like you normally would::
+Now you can compile with SCons like you normally would:
+
+::
 
     scons platform=macos
 

+ 24 - 8
contributing/development/compiling/compiling_for_web.rst

@@ -34,7 +34,9 @@ and ``source ./emsdk_env.sh``/``emsdk_env.bat``.
 
 Open a terminal and navigate to the root directory of the engine source code.
 Then instruct SCons to build the Web platform. Specify ``target`` as
-either ``template_release`` for a release build or ``template_debug`` for a debug build::
+either ``template_release`` for a release build or ``template_debug`` for a debug build:
+
+::
 
     scons platform=web target=template_release
     scons platform=web target=template_debug
@@ -42,13 +44,17 @@ either ``template_release`` for a release build or ``template_debug`` for a debu
 By default, the :ref:`JavaScriptBridge singleton <doc_web_javascript_bridge>` will be built
 into the engine. Official export templates also have the JavaScript singleton
 enabled. Since ``eval()`` calls can be a security concern, the
-``javascript_eval`` option can be used to build without the singleton::
+``javascript_eval`` option can be used to build without the singleton:
+
+::
 
     scons platform=web target=template_release javascript_eval=no
     scons platform=web target=template_debug javascript_eval=no
 
 By default, WebWorker threads support is enabled. To disable it and only use a single thread,
-the ``threads`` option can be used to build the web template without threads support::
+the ``threads`` option can be used to build the web template without threads support:
+
+::
 
     scons platform=web target=template_release threads=no
     scons platform=web target=template_debug threads=no
@@ -59,11 +65,15 @@ the resulting file will be placed in the ``bin`` subdirectory. Its name is
 for debug.
 
 Finally, rename the zip archive to ``web_release.zip`` for the
-release template::
+release template:
+
+::
 
     mv bin/godot.web.template_release.wasm32.zip bin/web_release.zip
 
-And ``web_debug.zip`` for the debug template::
+And ``web_debug.zip`` for the debug template:
+
+::
 
     mv bin/godot.web.template_debug.wasm32.zip bin/web_debug.zip
 
@@ -75,7 +85,9 @@ performance and compatibility reasons. See the
 :ref:`export page <doc_javascript_export_options>` for more info.
 
 You can build the export templates using the option ``dlink_enabled=yes``
-to enable GDExtension support::
+to enable GDExtension support:
+
+::
 
     scons platform=web dlink_enabled=yes target=template_release
     scons platform=web dlink_enabled=yes target=template_debug
@@ -84,7 +96,9 @@ Once finished, the resulting file will be placed in the ``bin`` subdirectory.
 Its name will have ``_dlink`` added.
 
 Finally, rename the zip archives to ``web_dlink_release.zip`` and
-``web_dlink_release.zip`` for the release template::
+``web_dlink_release.zip`` for the release template:
+
+::
 
     mv bin/godot.web.template_release.wasm32.dlink.zip bin/web_dlink_release.zip
     mv bin/godot.web.template_debug.wasm32.dlink.zip bin/web_dlink_debug.zip
@@ -94,7 +108,9 @@ Building the editor
 
 It is also possible to build a version of the Godot editor that can run in the
 browser. The editor version is not recommended
-over the native build. You can build the editor with::
+over the native build. You can build the editor with:
+
+::
 
     scons platform=web target=editor
 

+ 30 - 10
contributing/development/compiling/compiling_for_windows.rst

@@ -38,13 +38,17 @@ For compiling under Windows, the following is required:
   Studio releases.
 
 .. note:: If you have `Scoop <https://scoop.sh/>`_ installed, you can easily
-          install MinGW and other dependencies using the following command::
+          install MinGW and other dependencies using the following command:
+
+          ::
 
               scoop install python mingw
 
           Scons will still need to be installed via pip
 .. note:: If you have `MSYS2 <https://www.msys2.org/>`_ installed, you can easily
-          install MinGW and other dependencies using the following command::
+          install MinGW and other dependencies using the following command:
+
+          ::
 
               pacman -S mingw-w64-x86_64-python3-pip mingw-w64-x86_64-gcc  \
                   mingw-w64-i686-python3-pip mingw-w64-i686-gcc make
@@ -61,7 +65,9 @@ For compiling under Windows, the following is required:
 Setting up SCons
 ----------------
 
-To install SCons, open the command prompt and run the following command::
+To install SCons, open the command prompt and run the following command:
+
+::
 
     python -m pip install scons
 
@@ -205,7 +211,9 @@ optional PIX and Agility SDK components).
              which is needed to generate some files.
           2. Clone the `godot-nir-static <https://github.com/godotengine/godot-nir-static>`_
              directory and navigate to it.
-          3. Run the following::
+          3. Run the following:
+
+          ::
 
               git submodule update --init
               ./update_mesa.sh
@@ -244,7 +252,9 @@ Optionally, you can compile with the following for additional features:
           developer mode in Windows; otherwise it won't be used.
 
 .. note:: If you want to use a PIX with MinGW build, navigate to PIX runtime
-          directory and use the following commands to generate import library::
+          directory and use the following commands to generate import library:
+
+          ::
 
             # For x86-64:
             gendef ./bin/x64/WinPixEventRuntime.dll
@@ -300,7 +310,9 @@ To compile Godot with statically linked ANGLE:
 
           1. Clone the `godot-angle-static <https://github.com/godotengine/godot-angle-static>`_
              directory and navigate to it.
-          2. Run the following command::
+          2. Run the following command:
+
+          ::
 
               git submodule update --init
               ./update_angle.sh
@@ -330,7 +342,9 @@ Folder-based editors don't require any particular setup to start working with Go
 codebase. To edit projects with Visual Studio they need to be set up as a solution.
 
 You can create a Visual Studio solution via SCons by running SCons with
-the ``vsproj=yes`` parameter, like this::
+the ``vsproj=yes`` parameter, like this:
+
+::
 
    scons platform=windows vsproj=yes
 
@@ -373,7 +387,9 @@ The package names may differ based on your distribution, here are some known one
 +----------------+--------------------------------------------------------------+
 
 Before attempting the compilation, SCons will check for
-the following binaries in your ``PATH`` environment variable::
+the following binaries in your ``PATH`` environment variable:
+
+::
 
     # for MinGW-w64
     i686-w64-mingw32-gcc
@@ -386,7 +402,9 @@ the following binaries in your ``PATH`` environment variable::
 
 If the binaries are not located in the ``PATH`` (e.g. ``/usr/bin``),
 you can define the following environment variable to give a hint to
-the build system::
+the build system:
+
+::
 
     export MINGW_PREFIX="/path/to/mingw"
 
@@ -452,7 +470,9 @@ following location, replacing ``<version>`` with the version identifier
 
     %APPDATA%\Godot\export_templates\<version>\
 
-With the following names::
+With the following names:
+
+::
 
     windows_debug_x86_32_console.exe
     windows_debug_x86_32.exe

+ 3 - 1
contributing/development/compiling/compiling_with_dotnet.rst

@@ -33,7 +33,9 @@ These source files must be generated before building the managed libraries.
 They can be generated by any .NET-enabled Godot editor binary by running it with
 the parameters ``--headless --generate-mono-glue`` followed by the path to an
 output directory.
-This path must be ``modules/mono/glue`` in the Godot directory::
+This path must be ``modules/mono/glue`` in the Godot directory:
+
+::
 
     <godot_binary> --headless --generate-mono-glue modules/mono/glue
 

+ 3 - 1
contributing/development/compiling/index.rst

@@ -9,7 +9,9 @@ Building from source
 
 Godot prides itself on being very easy to build, by C++ projects' standards.
 :ref:`Godot uses the SCons build system <doc_faq_why_scons>`, and after the initial
-setup compiling the engine for your current platform should be as easy as running::
+setup compiling the engine for your current platform should be as easy as running:
+
+::
 
     scons
 

+ 12 - 4
contributing/development/compiling/introduction_to_the_buildsystem.rst

@@ -8,18 +8,24 @@ Introduction to the buildsystem
 
 Godot is a primarily C++ project and it :ref:`uses the SCons build system. <doc_faq_why_scons>`
 We love SCons for how maintainable and easy to set up it makes our buildsystem. And thanks to
-that compiling Godot from source can be as simple as running::
+that compiling Godot from source can be as simple as running:
+
+::
 
     scons
 
 This produces an editor build for your current platform, operating system, and architecture.
 You can change what gets built by specifying a target, a platform, and/or an architecture.
-For example, to build an export template used for running exported games, you can run::
+For example, to build an export template used for running exported games, you can run:
+
+::
 
     scons target=template_release
 
 If you plan to debug or develop the engine, then you might want to enable the ``dev_build``
-option to enable dev-only debugging code::
+option to enable dev-only debugging code:
+
+::
 
     scons dev_build=yes
 
@@ -90,7 +96,9 @@ Resulting binary
 ----------------
 
 The resulting binaries will be placed in the ``bin/`` subdirectory,
-generally with this naming convention::
+generally with this naming convention:
+
+::
 
     godot.<platform>.<target>[.dev][.double].<arch>[.<extra_suffix>][.<ext>]
 

+ 8 - 4
contributing/development/core_and_modules/custom_modules_in_cpp.rst

@@ -535,11 +535,15 @@ main ``doc/classes`` directory.
 .. tip::
 
     You can use Git to check if you have missed some of your classes by checking the
-    untracked files with ``git status``. For example::
+    untracked files with ``git status``. For example:
+
+    ::
 
         git status
 
-    Example output::
+    Example output:
+
+    ::
 
         Untracked files:
             (use "git add <file>..." to include in what will be committed)
@@ -561,9 +565,9 @@ to an another folder, and just copy over the files that you need.
 
 Run command:
 
-   ::
+::
 
-      bin/<godot_binary> --doctool .
+    bin/<godot_binary> --doctool .
 
 Now if you go to the ``godot/modules/summator/doc_classes`` folder, you will see
 that it contains a ``Summator.xml`` file, or any other classes, that you referenced

+ 3 - 1
contributing/development/core_and_modules/custom_resource_format_loaders.rst

@@ -362,7 +362,9 @@ project's root folder:
       ]
     }
 
-Then attach the following script to any node::
+Then attach the following script to any node:
+
+::
 
     extends Node
 

+ 3 - 1
contributing/development/debugging/macos_debug.rst

@@ -34,7 +34,9 @@ Create an ``editor.entitlements`` text file with the following contents:
         </dict>
     </plist>
 
-Then use the following command to re-sign the editor::
+Then use the following command to re-sign the editor:
+
+::
 
     codesign -s - --deep --force --options=runtime --entitlements ./editor.entitlements ./path/to/Godot.app
 

+ 3 - 1
contributing/development/debugging/vulkan/vulkan_validation_layers.rst

@@ -164,7 +164,9 @@ Copy libraries
 Copy libraries from ``Vulkan-ValidationLayers/build-android/libs`` to
 ``godot/platform/android/java/app/libs/debug/vulkan_validation_layers``.
 
-Your Godot source directory tree should look like on the example below::
+Your Godot source directory tree should look like on the example below:
+
+::
 
     godot
     |-- platform

+ 6 - 2
contributing/documentation/docs_image_guidelines.rst

@@ -160,7 +160,9 @@ All images are stored in folders named ``img`` next to the page they are used in
 
 To add your image, add it to the ``img`` folder that's in the same folder as the
 ``.rst`` file for the page (create it if it doesn't exist). In the ``.rst`` page,
-images should be included with the following code snippet::
+images should be included with the following code snippet:
+
+::
 
     .. image:: img/documentation_image.webp
 
@@ -245,7 +247,9 @@ All videos are stored in folders named ``video`` next to the page they are used
 
 To add your video, add it to the ``video`` folder that's in the same folder as the
 ``.rst`` file for the page (create it if it doesn't exist). In the ``.rst`` page,
-videos should be included with the following code snippet::
+videos should be included with the following code snippet:
+
+::
 
     .. video:: video/csg_tools.webm
        :alt: Put a text description of the video here

+ 54 - 2
contributing/documentation/docs_writing_guidelines.rst

@@ -559,7 +559,7 @@ Emphasis
 
 Use either **bold style** or *italic style* to emphasize words or sentences.
 In most cases, either **bold** or *italics* is fine. Use whichever seems best,
-or whatever the page already uses. 
+or whatever the page already uses.
 
 Prefer using **bold style** for simple emphasis.
 
@@ -643,6 +643,58 @@ rendered, prefer splitting the setting name and the section when the link is lon
     - In the project settings under **Application > Run**, set :ref:`Max FPS<class_ProjectSettings_property_application/run/max_fps>` to ``60``.
     - In **Project Settings > Application > Run**, set :ref:`Max FPS<class_ProjectSettings_property_application/run/max_fps>` to ``60``.
 
+Code blocks and adominitions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Code blocks should use the ``::`` syntax on its own line. Do not use the short
+form where it's at the end of a paragraph, as the trailing ``::`` would be included
+in the localizable string otherwise. Weblate would show a warning due to the trailing ``::``,
+and if the localized string does not end with ``::``, it would break the code block entirely
+in the translated manual.
+
+
+**Bad:**
+
+::
+
+    This is a code block::
+
+        The code block's contents.
+
+**Good:**
+
+::
+
+    This is a code block:
+
+    ::
+
+        The code block's contents.
+
+As for admonitions (note, warning, etc. blocks), you should write the admonition tag on its own line,
+then the admonition's contents indented by 4 spaces. Do not write the first line of the contents
+on the same line as the admonition tag.
+
+**Bad:**
+
+::
+
+    This is an admonition:
+
+    .. note:: First line of the note's contents.
+              Second line of the note's contents.
+
+**Good:**
+
+::
+
+    This is an admonition:
+
+    .. note::
+
+        First line of the note's contents.
+        Second line of the note's contents.
+
 .. _doc_docs_writing_guidelines_manually_wrapping_lines:
 
 Manually wrapping lines
@@ -759,6 +811,6 @@ Follow these guidelines for when to refer to a specific Godot version:
 - If the default approach to a problem is changed in a 4.x minor version, **do
   specify** the minor version in which a new default approach was added. For example,
   the change from ``TileMap`` to ``TileMapLayer`` in 4.3.
-- If a feature was added in a 3.x major or minor version, **do not specify** when 
+- If a feature was added in a 3.x major or minor version, **do not specify** when
   the feature was added. These features are old enough that the exact version
   in which they were added is not relevant.

+ 3 - 1
contributing/documentation/editor_and_docs_localization.rst

@@ -250,7 +250,9 @@ Online documentation (RST)
 
 The documentation translations originate from reStructuredText (RST) files,
 which also use their own markup syntax to style text, create internal and
-external links, etc. Here are some examples::
+external links, etc. Here are some examples:
+
+::
 
     # "development" is styled bold.
     # "Have a look here" is a link pointing to https://docs.godotengine.org/en/latest.

+ 3 - 1
tutorials/assets_pipeline/importing_3d_scenes/import_configuration.rst

@@ -478,7 +478,9 @@ script.
 
 For example: include all tracks in animations with names ending in ``"_Loop"``,
 but discard any tracks affecting a ``"Skeleton"`` which end in ``"Control"``,
-unless they have ``"Arm"`` in their name::
+unless they have ``"Arm"`` in their name:
+
+::
 
     @+*_Loop
     +*

+ 6 - 2
tutorials/best_practices/project_organization.rst

@@ -113,7 +113,9 @@ in general).
 
 On Windows 10, to further avoid mistakes related to case sensitivity,
 you can also make the project folder case-sensitive. After enabling the Windows
-Subsystem for Linux feature, run the following command in a PowerShell window::
+Subsystem for Linux feature, run the following command in a PowerShell window:
+
+::
 
     # To enable case-sensitivity:
     fsutil file setcasesensitiveinfo <path to project folder> enable
@@ -123,6 +125,8 @@ Subsystem for Linux feature, run the following command in a PowerShell window::
 
 If you haven't enabled the Windows Subsystem for Linux, you can enter the
 following line in a PowerShell window *running as Administrator* then reboot
-when asked::
+when asked:
+
+::
 
     Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

+ 3 - 1
tutorials/export/exporting_projects.rst

@@ -248,7 +248,9 @@ depending on your needs.
     Due to a `known bug <https://github.com/godotengine/godot/pull/42123>`__,
     when using a ZIP file as a pack file, the exported binary will not try to use
     it automatically. Therefore, you have to create a *launcher script* that
-    the player can double-click or run from a terminal to launch the project::
+    the player can double-click or run from a terminal to launch the project:
+
+    ::
 
         :: launch.bat (Windows)
         @echo off

+ 3 - 1
tutorials/i18n/pseudolocalization.rst

@@ -79,7 +79,9 @@ and then calling
 :ref:`TranslationServer.reload_pseudolocalization() <class_TranslationServer_method_reload_pseudolocalization>`
 which reparses the pseudolocalization properties and reloads the pseudolocalization.
 The following code snippet shall turn on ``replace_with_accents`` and ``double_vowels`` properties
-and then call ``reload_pseudolocalization()`` for the changes to get reflected::
+and then call ``reload_pseudolocalization()`` for the changes to get reflected:
+
+::
 
     ProjectSettings.set_setting("internationalization/pseudolocalization/replace_with_accents", true)
     ProjectSettings.set_setting("internationalization/pseudolocalization/double_vowels", true)

+ 3 - 1
tutorials/io/binary_serialization_api.rst

@@ -34,7 +34,9 @@ little-endian-encoded. All packets have a 4-byte header representing an
 integer, specifying the type of data.
 
 The lowest value two bytes are used to determine the type, while the highest value
-two bytes contain flags::
+two bytes contain flags:
+
+::
 
     base_type = val & 0xFFFF;
     flags = val >> 16;

+ 3 - 1
tutorials/migrating/upgrading_to_godot_4.1.rst

@@ -281,7 +281,9 @@ There are two small changes:
 #. The first argument changes from ``const GDExtensionInterface *p_interface`` to ``GDExtensionInterfaceGetProcAddress p_get_proc_address``
 #. The constructor for the `init_obj` variable now receives ``p_get_proc_address`` as its first parameter
 
-You also need to add an extra ``compatibility_minimum`` line to your ``.gdextension`` file, so that it looks something like::
+You also need to add an extra ``compatibility_minimum`` line to your ``.gdextension`` file, so that it looks something like:
+
+::
 
   [configuration]
 

+ 6 - 2
tutorials/physics/physics_introduction.rst

@@ -163,7 +163,9 @@ can use binary, hexadecimal, or decimal notation for layer masks, depending
 on your preference.
 
 The code equivalent of the above example where layers 1, 3 and 4 were enabled
-would be as follows::
+would be as follows:
+
+::
 
     # Example: Setting mask value for enabling layers 1, 3 and 4
 
@@ -181,7 +183,9 @@ would be as follows::
     pow(2, 1-1) + pow(2, 3-1) + pow(2, 4-1)
 
 You can also set bits independently by calling ``set_collision_layer_value(layer_number, value)``
-or ``set_collision_mask_value(layer_number, value)`` on any given :ref:`CollisionObject2D <class_CollisionObject2D>` as follows::
+or ``set_collision_mask_value(layer_number, value)`` on any given :ref:`CollisionObject2D <class_CollisionObject2D>` as follows:
+
+::
 
     # Example: Setting mask value to enable layers 1, 3, and 4.
 

+ 50 - 38
tutorials/platform/android/android_plugin.rst

@@ -128,11 +128,13 @@ Use the following steps if you have a v1 Android plugin you want to migrate to v
 2. Update the Godot Android library build dependency:
 
     - You can continue using the ``godot-lib.<version>.<status>.aar`` binary from `Godot's download page <https://godotengine.org/download>`_ if that's your preference. Make sure it's updated to the latest stable version.
-    - Or you can switch to the MavenCentral provided dependency::
+    - Or you can switch to the MavenCentral provided dependency:
 
-        dependencies {
-            implementation("org.godotengine:godot:4.2.0.stable")
-        }
+::
+
+    dependencies {
+        implementation("org.godotengine:godot:4.2.0.stable")
+    }
 
 3. After updating the Godot Android library dependency, sync or build the plugin and resolve any compile errors:
 
@@ -150,46 +152,48 @@ As mentioned, a v2 Android plugin is now provided to the Godot Editor as an ``Ed
 2. Add the `tool script <https://docs.godotengine.org/en/stable/tutorials/plugins/editor/making_plugins.html#the-script-file>`_ for the export functionality within the plugin directory (e.g: in ``addons/<plugin_name>/``)
 
     - The created script must be a ``@tool`` script, or else it will not work properly
-    - The export tool script is used to configure the Android plugin and hook it within the Godot Editor's export process. It should look something like this::
+    - The export tool script is used to configure the Android plugin and hook it within the Godot Editor's export process. It should look something like this:
+
+::
 
-        @tool
-        extends EditorPlugin
+    @tool
+    extends EditorPlugin
 
-        # A class member to hold the editor export plugin during its lifecycle.
-        var export_plugin : AndroidExportPlugin
+    # A class member to hold the editor export plugin during its lifecycle.
+    var export_plugin : AndroidExportPlugin
 
-        func _enter_tree():
-            # Initialization of the plugin goes here.
-            export_plugin = AndroidExportPlugin.new()
-            add_export_plugin(export_plugin)
+    func _enter_tree():
+        # Initialization of the plugin goes here.
+        export_plugin = AndroidExportPlugin.new()
+        add_export_plugin(export_plugin)
 
 
-        func _exit_tree():
-            # Clean-up of the plugin goes here.
-            remove_export_plugin(export_plugin)
-            export_plugin = null
+    func _exit_tree():
+        # Clean-up of the plugin goes here.
+        remove_export_plugin(export_plugin)
+        export_plugin = null
 
 
-        class AndroidExportPlugin extends EditorExportPlugin:
-            # Plugin's name.
-            var _plugin_name = "<plugin_name>"
+    class AndroidExportPlugin extends EditorExportPlugin:
+        # Plugin's name.
+        var _plugin_name = "<plugin_name>"
 
-            # Specifies which platform is supported by the plugin.
-            func _supports_platform(platform):
-                if platform is EditorExportPlatformAndroid:
-                    return true
-                return false
+        # Specifies which platform is supported by the plugin.
+        func _supports_platform(platform):
+            if platform is EditorExportPlatformAndroid:
+                return true
+            return false
 
-            # Return the paths of the plugin's AAR binaries relative to the 'addons' directory.
-            func _get_android_libraries(platform, debug):
-                if debug:
-                    return PackedStringArray(["<paths_to_debug_android_plugin_aar_binaries>"])
-                else:
-                    return PackedStringArray(["<paths_to_release_android_plugin_aar_binaries>"])
+        # Return the paths of the plugin's AAR binaries relative to the 'addons' directory.
+        func _get_android_libraries(platform, debug):
+            if debug:
+                return PackedStringArray(["<paths_to_debug_android_plugin_aar_binaries>"])
+            else:
+                return PackedStringArray(["<paths_to_release_android_plugin_aar_binaries>"])
 
-            # Return the plugin's name.
-            func _get_name():
-                return _plugin_name
+        # Return the plugin's name.
+        func _get_name():
+            return _plugin_name
 
 
     - Here are the set of `EditorExportPlugin APIs <https://docs.godotengine.org/en/stable/classes/class_editorexportplugin.html>`_ most relevant to use in this tool script:
@@ -206,7 +210,9 @@ As mentioned, a v2 Android plugin is now provided to the Godot Editor as an ``Ed
         to the app's manifest which are preserved when the Godot Editor is updated, resolving a long standing issue with v1 Android plugins.
 
 
-3. Create a ``plugin.cfg``. This is an INI file with metadata about your plugin::
+3. Create a ``plugin.cfg``. This is an INI file with metadata about your plugin:
+
+::
 
       [plugin]
 
@@ -248,7 +254,9 @@ At build time, the contents of the ``export_scripts_template`` directory as well
     +--plugin.gdextension       # GDExtension config file
 
 
-Here is what the ``plugin.gdextension`` config file should look like::
+Here is what the ``plugin.gdextension`` config file should look like:
+
+::
 
     [configuration]
 
@@ -298,7 +306,9 @@ Using a v2 Android plugin
 
 7. In the ``Android export preset``, scroll to ``Gradle Build`` and set ``Use Gradle Build`` to ``true``
 
-8. Update the project's scripts as needed to access the plugin's functionality. For example::
+8. Update the project's scripts as needed to access the plugin's functionality. For example:
+
+::
 
     if Engine.has_singleton("MyPlugin"):
             var singleton = Engine.get_singleton("MyPlugin")
@@ -332,7 +342,9 @@ Simplify access to the exposed Java / Kotlin APIs
 To make it easier to access the exposed Java / Kotlin APIs in the Godot Editor, it's recommended to
 provide one (or multiple) gdscript wrapper class(es) for your plugin users to interface with.
 
-For example::
+For example:
+
+::
 
     class_name PluginInterface extends Object
 

+ 3 - 1
tutorials/platform/ios/ios_plugin.rst

@@ -80,7 +80,9 @@ To build an iOS plugin:
 
     -   The configuration file extension must be ``gdip`` (e.g.: ``MyPlugin.gdip``).
 
-    -   The configuration file format is as follow::
+    -   The configuration file format is as follow:
+
+    ::
 
             [config]
             name="MyPlugin"

+ 12 - 4
tutorials/scripting/evaluating_expressions.rst

@@ -83,7 +83,9 @@ Passing variables to an expression
 
 You can pass variables to an expression. These variables will then
 become available in the expression's "context" and will be substituted when used
-in the expression::
+in the expression:
+
+::
 
     var expression = Expression.new()
     # Define the variable names first in the second parameter of `parse()`.
@@ -105,7 +107,9 @@ expression has no base instance associated to it.
 
 When calling :ref:`Expression.execute() <class_Expression_method_execute>`,
 you can set the value of the ``base_instance`` parameter to a specific object
-instance such as ``self``, another script instance or even a singleton::
+instance such as ``self``, another script instance or even a singleton:
+
+::
 
     func double(number):
         return number * 2
@@ -141,7 +145,9 @@ Associating a base instance allows doing the following:
 Example script
 --------------
 
-The script below demonstrates what the Expression class is capable of::
+The script below demonstrates what the Expression class is capable of:
+
+::
 
     const DAYS_IN_YEAR = 365
     var script_member_variable = 1000
@@ -191,7 +197,9 @@ The script below demonstrates what the Expression class is capable of::
         # The method's return value is also the expression's return value.
         return 0
 
-The output from the script will be::
+The output from the script will be:
+
+::
 
     false
     true

+ 159 - 53
tutorials/scripting/gdscript/gdscript_basics.rst

@@ -372,7 +372,9 @@ There are also two constructs that look like literals, but actually are not:
 +---------------------------------+-------------------------------------------+
 
 Integers and floats can have their numbers separated with ``_`` to make them more readable.
-The following ways to write numbers are all valid::
+The following ways to write numbers are all valid:
+
+::
 
     12_345_678  # Equal to 12345678.
     3.141_592_7  # Equal to 3.1415927.
@@ -455,7 +457,9 @@ Every annotation starts with the ``@`` character and is specified by a name. A
 detailed description and example for each annotation can be found inside the
 :ref:`GDScript class reference <class_@GDScript>`.
 
-For instance, you can use it to export a value to the editor::
+For instance, you can use it to export a value to the editor:
+
+::
 
     @export_range(1, 100, 1, "or_greater")
     var ranged_var: int = 50
@@ -463,7 +467,9 @@ For instance, you can use it to export a value to the editor::
 For more information about exporting properties, read the :ref:`GDScript exports <doc_gdscript_exports>`
 article.
 
-Any constant expression compatible with the required argument type can be passed as an annotation argument value::
+Any constant expression compatible with the required argument type can be passed as an annotation argument value:
+
+::
 
     const MAX_SPEED = 120.0
 
@@ -474,7 +480,9 @@ Annotations can be specified one per line or all in the same line. They affect
 the next statement that isn't an annotation. Annotations can have arguments sent
 between parentheses and separated by commas.
 
-Both of these are the same::
+Both of these are the same:
+
+::
 
     @annotation_a
     @annotation_b
@@ -503,7 +511,9 @@ be obtained when a call to ``Node._ready()`` is made.
 This can get a little cumbersome, especially when nodes and external
 references pile up. For this, GDScript has the ``@onready`` annotation, that
 defers initialization of a member variable until ``_ready()`` is called. It
-can replace the above code with a single line::
+can replace the above code with a single line:
+
+::
 
     @onready var my_label = get_node("MyLabel")
 
@@ -512,7 +522,9 @@ can replace the above code with a single line::
     Applying ``@onready`` and any ``@export`` annotation to the same variable
     doesn't work as you might expect. The ``@onready`` annotation will cause
     the default value to be set after the ``@export`` takes effect and will
-    override it::
+    override it:
+
+    ::
 
         @export var a = "init_value_a"
         @onready @export var b = "init_value_b"
@@ -958,7 +970,9 @@ identifier), and must be string literals.
     }
 
 To add a key to an existing dictionary, access it like an existing key and
-assign to it::
+assign to it:
+
+::
 
     var d = {} # Create an empty Dictionary.
     d.waiting = 14 # Add String "waiting" as a key and assign the value 14 to it.
@@ -1053,7 +1067,9 @@ after the variable name, followed by the type.
     var my_node: Node = Sprite2D.new()
 
 If the variable is initialized within the declaration, the type can be inferred, so
-it's possible to omit the type name::
+it's possible to omit the type name:
+
+::
 
     var my_vector2 := Vector2() # 'my_vector2' is of type 'Vector2'.
     var my_node := Sprite2D.new() # 'my_node' is of type 'Sprite2D'.
@@ -1103,7 +1119,9 @@ Member variables are initialized in the following order:
 
     You can specify a complex expression as a variable initializer, including function calls.
     Make sure the variables are initialized in the correct order, otherwise your values
-    may be overwritten. For example::
+    may be overwritten. For example:
+
+    ::
 
         var a: int = proxy("a", 1)
         var b: int = proxy("b", 2)
@@ -1117,7 +1135,9 @@ Member variables are initialized in the following order:
         func _init() -> void:
             print(_data)
 
-    Will print::
+    Will print:
+
+    ::
 
         { "a": 1 }
         { "a": 1, "b": 2 }
@@ -1129,7 +1149,9 @@ Member variables are initialized in the following order:
 Static variables
 ~~~~~~~~~~~~~~~~
 
-A class member variable can be declared static::
+A class member variable can be declared static:
+
+::
 
     static var a
 
@@ -1183,7 +1205,9 @@ and every instance have the same ``max_id`` value, because the variable is stati
         print(person1.max_id) # 2
         print(person2.max_id) # 2
 
-Static variables can have type hints, setters and getters::
+Static variables can have type hints, setters and getters:
+
+::
 
     static var balance: int = 0
 
@@ -1193,7 +1217,9 @@ Static variables can have type hints, setters and getters::
         set(value):
             balance = -value
 
-A base class static variable can also be accessed via a child class::
+A base class static variable can also be accessed via a child class:
+
+::
 
     class A:
         static var x = 1
@@ -1262,7 +1288,9 @@ engine will raise an error.
     my_int = Vector2() as int # A Vector2 can't be converted to int, this will cause an error.
 
 Casting is also useful to have better type-safe variables when interacting with
-the scene tree::
+the scene tree:
+
+::
 
     # Will infer the variable to be of type Sprite2D.
     var my_sprite := $Character as Sprite2D
@@ -1292,7 +1320,9 @@ We recommend using constants whenever a value is not meant to change.
     const H = A + 20 # Constant expression: 25 (`A` is a constant).
 
 Although the type of constants is inferred from the assigned value, it's also
-possible to add explicit type specification::
+possible to add explicit type specification:
+
+::
 
     const A: int = 5
     const B: Vector2 = Vector2()
@@ -1368,7 +1398,9 @@ function's first argument, unlike Python).
 
 A function can ``return`` at any point. The default return value is ``null``.
 
-If a function contains only one line of code, it can be written on one line::
+If a function contains only one line of code, it can be written on one line:
+
+::
 
     func square(a): return a * a
 
@@ -1377,12 +1409,16 @@ If a function contains only one line of code, it can be written on one line::
     func empty_function(): pass
 
 Functions can also have type specification for the arguments and for the return
-value. Types for arguments can be added in a similar way to variables::
+value. Types for arguments can be added in a similar way to variables:
+
+::
 
     func my_function(a: int, b: String):
         pass
 
-If a function argument has a default value, it's possible to infer the type::
+If a function argument has a default value, it's possible to infer the type:
+
+::
 
     func my_function(int_arg := 42, String_arg := "string"):
         pass
@@ -1459,7 +1495,9 @@ Lambda functions can be named for debugging purposes (the name is displayed in t
     var lambda = func my_lambda(x):
         print(x)
 
-You can specify type hints for lambda functions in the same way as for regular ones::
+You can specify type hints for lambda functions in the same way as for regular ones:
+
+::
 
     var lambda := func (x: int) -> void:
         print(x)
@@ -1470,7 +1508,9 @@ is required (you can't omit ``return``)::
     var lambda = func (x): return x ** 2
     print(lambda.call(2)) # Prints `4`.
 
-Lambda functions capture the local environment::
+Lambda functions capture the local environment:
+
+::
 
     var x = 42
     var lambda = func ():
@@ -1480,7 +1520,9 @@ Lambda functions capture the local environment::
 .. warning::
 
     Local variables are captured by value once, when the lambda is created.
-    So they won't be updated in the lambda if reassigned in the outer function::
+    So they won't be updated in the lambda if reassigned in the outer function:
+
+    ::
 
         var x = 42
         var lambda = func (): print(x)
@@ -1489,7 +1531,9 @@ Lambda functions capture the local environment::
         lambda.call() # Prints `42`.
 
     Also, a lambda cannot reassign an outer local variable. After exiting the lambda,
-    the variable will be unchanged, because the lambda capture implicitly shadows it::
+    the variable will be unchanged, because the lambda capture implicitly shadows it:
+
+    ::
 
         var x = 42
         var lambda = func ():
@@ -1500,7 +1544,9 @@ Lambda functions capture the local environment::
         print(x) # Prints `42`.
 
     However, if you use pass-by-reference data types (arrays, dictionaries, and objects),
-    then the content changes are shared until you reassign the variable::
+    then the content changes are shared until you reassign the variable:
+
+    ::
 
         var a = []
         var lambda = func ():
@@ -1515,7 +1561,9 @@ Static functions
 ~~~~~~~~~~~~~~~~
 
 A function can be declared static. When a function is static, it has no access to the instance member variables or ``self``.
-A static function has access to static variables. Also static functions are useful to make libraries of helper functions::
+A static function has access to static variables. Also static functions are useful to make libraries of helper functions:
+
+::
 
     static func sum2(a, b):
         return a + b
@@ -1540,7 +1588,9 @@ statement too, though only calls are reasonable to use as statements since other
 Expressions return values that can be assigned to valid targets. Operands to some operator can be another
 expression. An assignment is not an expression and thus does not return any value.
 
-Here are some examples of expressions::
+Here are some examples of expressions:
+
+::
 
     2 + 2 # Binary operation.
     -5 # Unary operation.
@@ -1609,7 +1659,9 @@ nature of the tab-based indentation, ``elif`` can be used instead of
     else:
         statement(s)
 
-Short statements can be written on the same line as the condition::
+Short statements can be written on the same line as the condition:
+
+::
 
     if 1 + 1 == 2: return 2 + 2
     else:
@@ -1617,14 +1669,18 @@ Short statements can be written on the same line as the condition::
         return x
 
 Sometimes, you might want to assign a different initial value based on a
-boolean expression. In this case, ternary-if expressions come in handy::
+boolean expression. In this case, ternary-if expressions come in handy:
+
+::
 
     var x = (value) if (expression) else (value)
     y += 3 if y < 10 else -1
 
 Ternary-if expressions can be nested to handle more than 2 cases. When nesting
 ternary-if expressions, it is recommended to wrap the complete expression over
-multiple lines to preserve readability::
+multiple lines to preserve readability:
+
+::
 
     var count = 0
 
@@ -1646,7 +1702,9 @@ multiple lines to preserve readability::
     print(fruit_alt)  # banana
 
 You may also wish to check if a value is contained within something. You can
-use an ``if`` statement combined with the ``in`` operator to accomplish this::
+use an ``if`` statement combined with the ``in`` operator to accomplish this:
+
+::
 
     # Check if a letter is in a string.
     var text = "abc"
@@ -1798,7 +1856,9 @@ The following pattern types are available:
 - Wildcard pattern
     This pattern matches everything. It's written as a single underscore.
 
-    It can be used as the equivalent of the ``default`` in a ``switch`` statement in other languages::
+    It can be used as the equivalent of the ``default`` in a ``switch`` statement in other languages:
+
+    ::
 
         match x:
             1:
@@ -1810,7 +1870,9 @@ The following pattern types are available:
 
 - Binding pattern
     A binding pattern introduces a new variable. Like the wildcard pattern, it matches everything - and also gives that value a name.
-    It's especially useful in array and dictionary patterns::
+    It's especially useful in array and dictionary patterns:
+
+    ::
 
         match x:
             1:
@@ -1935,7 +1997,9 @@ Registering named classes
 You can give your class a name to register it as a new type in Godot's
 editor. For that, you use the ``class_name`` keyword. You can optionally use
 the ``@icon`` annotation with a path to an image, to use it as an icon. Your
-class will then appear with its new icon in the editor::
+class will then appear with its new icon in the editor:
+
+::
 
    # item.gd
 
@@ -1974,7 +2038,9 @@ Here's a class file example:
         print(ResourceLoader.load("res://character.gd"))
         print(Character)
 
-If you want to use ``extends`` too, you can keep both on the same line::
+If you want to use ``extends`` too, you can keep both on the same line:
+
+::
 
     class_name MyNode extends Node
 
@@ -2094,7 +2160,9 @@ Inheritance uses the ``extends`` keyword::
     :ref:`class_RefCounted`.
 
 To check if a given instance inherits from a given class,
-the ``is`` keyword can be used::
+the ``is`` keyword can be used:
+
+::
 
     # Cache the enemy class.
     const Enemy = preload("enemy.gd")
@@ -2118,7 +2186,9 @@ call them, you can use ``super``::
         super(x) # Calls the same function on the super class.
 
 If you need to call a different function from the super class, you can specify
-the function name with the attribute operator::
+the function name with the attribute operator:
+
+::
 
     func overriding():
         return 0 # This overrides the method in the base class.
@@ -2150,12 +2220,16 @@ The class constructor, called on class instantiation, is named ``_init``. If you
 want to call the base class constructor, you can also use the ``super`` syntax.
 Note that every class has an implicit constructor that is always called
 (defining the default values of class variables). ``super`` is used to call the
-explicit constructor::
+explicit constructor:
+
+::
 
     func _init(arg):
        super("some_default", arg) # Call the custom base constructor.
 
-This is better explained through examples. Consider this scenario::
+This is better explained through examples. Consider this scenario:
+
+::
 
     # state.gd (inherited class).
     var entity = null
@@ -2200,7 +2274,9 @@ Static constructor
 ~~~~~~~~~~~~~~~~~~
 
 A static constructor is a static function ``_static_init`` that is called automatically
-when the class is loaded, after the static variables have been initialized::
+when the class is loaded, after the static variables have been initialized:
+
+::
 
     static var my_static_var = 1
 
@@ -2244,7 +2320,9 @@ Classes as resources
 Classes stored as files are treated as :ref:`GDScripts <class_GDScript>`. They
 must be loaded from disk to access them in other classes. This is done using
 either the ``load`` or ``preload`` functions (see below). Instancing of a loaded
-class resource is done by calling the ``new`` function on the class object::
+class resource is done by calling the ``new`` function on the class object:
+
+::
 
     # Load the class resource when calling load().
     var MyClass = load("myclass.gd")
@@ -2303,7 +2381,9 @@ or you need to reuse the code across multiple properties (but you can't distingu
     var my_prop:
         get = get_my_prop, set = set_my_prop
 
-This can also be done in the same line::
+This can also be done in the same line:
+
+::
 
     var my_prop: get = get_my_prop, set = set_my_prop
 
@@ -2322,7 +2402,9 @@ When a variable is initialized, the value of the initializer will be written dir
 Including if the ``@onready`` annotation is applied to the variable.
 
 Using the variable's name to set it inside its own setter or to get it inside its own getter will directly access the underlying member,
-so it won't generate infinite recursion and saves you from explicitly declaring another variable::
+so it won't generate infinite recursion and saves you from explicitly declaring another variable:
+
+::
 
     signal changed(new_value)
     var warns_when_changed = "some value":
@@ -2332,7 +2414,9 @@ so it won't generate infinite recursion and saves you from explicitly declaring
             changed.emit(value)
             warns_when_changed = value
 
-This also applies to the alternative syntax::
+This also applies to the alternative syntax:
+
+::
 
     var my_prop: set = set_my_prop
 
@@ -2342,7 +2426,9 @@ This also applies to the alternative syntax::
 .. warning::
 
     The exception does **not** propagate to other functions called in the setter/getter.
-    For example, the following code **will** cause an infinite recursion::
+    For example, the following code **will** cause an infinite recursion:
+
+::
 
         var my_prop:
             set(value):
@@ -2360,7 +2446,9 @@ By default, scripts don't run inside the editor and only the exported
 properties can be changed. In some cases, it is desired that they do run
 inside the editor (as long as they don't execute game code or manually
 avoid doing so). For this, the ``@tool`` annotation exists and must be
-placed at the top of the file::
+placed at the top of the file:
+
+::
 
     @tool
     extends Button
@@ -2454,7 +2542,9 @@ signals of nodes like :ref:`class_Button` or :ref:`class_RigidBody3D`.
 
 In the example below, we connect the ``health_depleted`` signal from a
 ``Character`` node to a ``Game`` node. When the ``Character`` node emits the
-signal, the game node's ``_on_character_health_depleted`` is called::
+signal, the game node's ``_on_character_health_depleted`` is called:
+
+::
 
     # game.gd
 
@@ -2552,7 +2642,9 @@ Building on the example above, let's say we want to display a log of the damage
 taken by each character on the screen, like ``Player1 took 22 damage.``. The
 ``health_changed`` signal doesn't give us the name of the character that took
 damage. So when we connect the signal to the in-game console, we can add the
-character's name using the bind method::
+character's name using the bind method:
+
+::
 
     # game.gd
 
@@ -2562,7 +2654,9 @@ character's name using the bind method::
 
         character_node.health_changed.connect(battle_log_node._on_Character_health_changed.bind(character_node.name))
 
-Our ``BattleLog`` node receives each bound element as an extra argument::
+Our ``BattleLog`` node receives each bound element as an extra argument:
+
+::
 
     # battle_log.gd
 
@@ -2582,7 +2676,9 @@ which wait until a signal is emitted before continuing execution. Using the ``aw
 call to a function that is also a coroutine will immediately return the control to the caller. When the signal is
 emitted (or the called coroutine finishes), it will resume execution from the point on where it stopped.
 
-For example, to stop execution until the user presses a button, you can do something like this::
+For example, to stop execution until the user presses a button, you can do something like this:
+
+::
 
     func wait_confirmation():
         print("Prompting user")
@@ -2590,7 +2686,9 @@ For example, to stop execution until the user presses a button, you can do somet
         print("User confirmed")
         return true
 
-In this case, the ``wait_confirmation`` becomes a coroutine, which means that the caller also needs to await it::
+In this case, the ``wait_confirmation`` becomes a coroutine, which means that the caller also needs to await it:
+
+::
 
     func request_confirmation():
         print("Will ask the user")
@@ -2600,20 +2698,26 @@ In this case, the ``wait_confirmation`` becomes a coroutine, which means that th
         else:
             print("User cancelled")
 
-Note that requesting a coroutine's return value without ``await`` will trigger an error::
+Note that requesting a coroutine's return value without ``await`` will trigger an error:
+
+::
 
     func wrong():
         var confirmed = wait_confirmation() # Will give an error.
 
 However, if you don't depend on the result, you can just call it asynchronously, which won't stop execution and won't
-make the current function a coroutine::
+make the current function a coroutine:
+
+::
 
     func okay():
         wait_confirmation()
         print("This will be printed immediately, before the user press the button.")
 
 If you use await with an expression that isn't a signal nor a coroutine, the value will be returned immediately and the
-function won't give the control back to the caller::
+function won't give the control back to the caller:
+
+::
 
     func no_wait():
         var x = await get_five()
@@ -2622,7 +2726,9 @@ function won't give the control back to the caller::
     func get_five():
         return 5
 
-This also means that returning a signal from a function that isn't a coroutine will make the caller await that signal::
+This also means that returning a signal from a function that isn't a coroutine will make the caller await that signal:
+
+::
 
     func get_signal():
         return $Button.button_up

+ 9 - 3
tutorials/scripting/gdscript/gdscript_documentation_comments.rst

@@ -45,7 +45,9 @@ Tags
 |                   | | ``@experimental: This class is unstable.``           |
 +-------------------+--------------------------------------------------------+
 
-For example::
+For example:
+
+::
 
     extends Node2D
     ## A brief description of the class's role and functionality.
@@ -98,13 +100,17 @@ Tags
 |              | | ``@experimental: This method is incomplete.``  |
 +--------------+--------------------------------------------------+
 
-For example::
+For example:
+
+::
 
     ## The description of the variable.
     ## @deprecated: Use [member other_var] instead.
     var my_var
 
-Alternatively, you can use inline documentation comments::
+Alternatively, you can use inline documentation comments:
+
+::
 
     signal my_signal ## My signal.
 

+ 18 - 6
tutorials/scripting/gdscript/gdscript_exports.rst

@@ -310,7 +310,9 @@ See :ref:`@export_flags <class_@GDScript_annotation_@export_flags>`.
 
 Integers used as bit flags can store multiple ``true``/``false`` (boolean)
 values in one property. By using the ``@export_flags`` annotation, they
-can be set from the editor::
+can be set from the editor:
+
+::
 
     # Set any of the given flags from the editor.
     @export_flags("Fire", "Water", "Earth", "Wind") var spell_elements = 0
@@ -320,18 +322,24 @@ has value 1, ``Water`` has value 2, ``Earth`` has value 4 and ``Wind``
 corresponds to value 8. Usually, constants should be defined accordingly (e.g.
 ``const ELEMENT_WIND = 8`` and so on).
 
-You can add explicit values using a colon::
+You can add explicit values using a colon:
+
+::
 
     @export_flags("Self:4", "Allies:8", "Foes:16") var spell_targets = 0
 
 Only power of 2 values are valid as bit flags options. The lowest allowed value
 is 1, as 0 means that nothing is selected. You can also add options that are a
-combination of other flags::
+combination of other flags:
+
+::
 
     @export_flags("Self:4", "Allies:8", "Self and Allies:12", "Foes:16")
     var spell_targets = 0
 
-Export annotations are also provided for the physics, render, and navigation layers defined in the project settings::
+Export annotations are also provided for the physics, render, and navigation layers defined in the project settings:
+
+::
 
     @export_flags_2d_physics var layers_2d_physics
     @export_flags_2d_render var layers_2d_render
@@ -367,7 +375,9 @@ of the selected option (i.e. ``0``, ``1``,  or ``2``).
 
     @export_enum("Warrior", "Magician", "Thief") var character_class: int
 
-You can add explicit values using a colon::
+You can add explicit values using a colon:
+
+::
 
     @export_enum("Slow:30", "Average:60", "Very Fast:200") var character_speed: int
 
@@ -377,7 +387,9 @@ If the type is String, the value will be stored as a string.
 
     @export_enum("Rebecca", "Mary", "Leah") var character_name: String
 
-If you want to set an initial value, you must specify it explicitly::
+If you want to set an initial value, you must specify it explicitly:
+
+::
 
     @export_enum("Rebecca", "Mary", "Leah") var character_name: String = "Rebecca"
 

+ 69 - 23
tutorials/scripting/gdscript/static_typing.rst

@@ -27,7 +27,9 @@ of your scripts.
 Imagine you're programming an inventory system. You code an ``Item`` class,
 then an ``Inventory``. To add items to the inventory, the people who work with
 your code should always pass an ``Item`` to the ``Inventory.add()`` method.
-With types, you can enforce this::
+With types, you can enforce this:
+
+::
 
     class_name Inventory
 
@@ -78,14 +80,18 @@ How to use static typing
 
 To define the type of a variable, parameter, or constant, write a colon after the name,
 followed by its type. E.g. ``var health: int``. This forces the variable's type
-to always stay the same::
+to always stay the same:
+
+::
 
     var damage: float = 10.5
     const MOVE_SPEED: float = 50.0
     func sum(a: float = 0.0, b: float = 0.0) -> float:
         return a + b
 
-Godot will try to infer types if you write a colon, but you omit the type::
+Godot will try to infer types if you write a colon, but you omit the type:
+
+::
 
     var damage := 10.5
     const MOVE_SPEED := 50.0
@@ -119,19 +125,25 @@ Here is a complete list of what can be used as a type hint:
 
 You can use any class, including your custom classes, as types. There are two ways
 to use them in scripts. The first method is to preload the script you want to use
-as a type in a constant::
+as a type in a constant:
+
+::
 
     const Rifle = preload("res://player/weapons/rifle.gd")
     var my_rifle: Rifle
 
 The second method is to use the ``class_name`` keyword when you create.
-For the example above, your ``rifle.gd`` would look like this::
+For the example above, your ``rifle.gd`` would look like this:
+
+::
 
     class_name Rifle
     extends Node2D
 
 If you use ``class_name``, Godot registers the ``Rifle`` type globally in the editor,
-and you can use it anywhere, without having to preload it into a constant::
+and you can use it anywhere, without having to preload it into a constant:
+
+::
 
     var my_rifle: Rifle
 
@@ -139,19 +151,25 @@ Specify the return type of a function with the arrow ``->``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To define the return type of a function, write a dash and a right angle bracket ``->``
-after its declaration, followed by the return type::
+after its declaration, followed by the return type:
+
+::
 
     func _process(delta: float) -> void:
         pass
 
 The type ``void`` means the function does not return anything. You can use any type,
-as with variables::
+as with variables:
+
+::
 
     func hit(damage: float) -> bool:
         health_points -= damage
         return health_points <= 0
 
-You can also use your own classes as return types::
+You can also use your own classes as return types:
+
+::
 
     # Adds an item to the inventory and returns it.
     func add(reference: Item, amount: int) -> Item:
@@ -221,7 +239,9 @@ and enums may be used as element types. Nested array types
     scores[0] = "lots"
 
 Since Godot 4.2, you can also specify a type for the loop variable in a ``for`` loop.
-For instance, you can write::
+For instance, you can write:
+
+::
 
     var names = ["John", "Marta", "Samantha", "Jimmy"]
     for name: String in names:
@@ -353,7 +373,9 @@ green at the left of the script editor.
 .. note::
 
     Safe lines do not always mean better or more reliable code. See the note above
-    about the ``as`` keyword. For example::
+    about the ``as`` keyword. For example:
+
+    ::
 
         @onready var node_1 := $Node1 as Type1 # Safe line.
         @onready var node_2: Type2 = $Node2 # Unsafe line.
@@ -377,7 +399,9 @@ and for your peers. It's easier for everyone to work together if you follow
 the same guidelines, and faster to read and understand other people's code.
 
 Typed code takes a little more writing, but you get the benefits we discussed
-above. Here's an example of the same, empty script, in a dynamic style::
+above. Here's an example of the same, empty script, in a dynamic style:
+
+::
 
     extends Node
 
@@ -389,7 +413,9 @@ above. Here's an example of the same, empty script, in a dynamic style::
     func _process(delta):
         pass
 
-And with static typing::
+And with static typing:
+
+::
 
     extends Node
 
@@ -403,12 +429,16 @@ And with static typing::
 
 As you can see, you can also use types with the engine's virtual methods.
 Signal callbacks, like any methods, can also use types. Here's a ``body_entered``
-signal in a dynamic style::
+signal in a dynamic style:
+
+::
 
     func _on_area_2d_body_entered(body):
         pass
 
-And the same callback, with type hints::
+And the same callback, with type hints:
+
+::
 
     func _on_area_entered(area: CollisionObject2D) -> void:
         pass
@@ -446,7 +476,9 @@ In this example, we aim to set a property and call a method on an object
 that has a script attached with ``class_name MyScript`` and that ``extends
 Node2D``. If we have a reference to the object as a ``Node2D`` (for instance,
 as it was passed to us by the physics system), we can first check if the
-property and method exist and then set and call them if they do::
+property and method exist and then set and call them if they do:
+
+::
 
     if "some_property" in node_2d:
         node_2d.some_property = 20  # Produces UNSAFE_PROPERTY_ACCESS warning.
@@ -459,7 +491,9 @@ However, this code will produce ``UNSAFE_PROPERTY_ACCESS`` and
 in the referenced type - in this case a ``Node2D``. To make these operations
 safe, you can first check if the object is of type ``MyScript`` using the
 ``is`` keyword and then declare a variable with the type ``MyScript`` on
-which you can set its properties and call its methods::
+which you can set its properties and call its methods:
+
+::
 
     if node_2d is MyScript:
         var my_script: MyScript = node_2d
@@ -468,7 +502,9 @@ which you can set its properties and call its methods::
 
 Alternatively, you can declare a variable and use the ``as`` operator to try
 to cast the object. You'll then want to check whether the cast was successful
-by confirming that the variable was assigned::
+by confirming that the variable was assigned:
+
+::
 
     var my_script := node_2d as MyScript
     if my_script != null:
@@ -482,7 +518,9 @@ In this example, we would like the label connected to an object entering our
 collision area to show the area's name. Once the object enters the collision
 area, the physics system sends a signal with a ``Node2D`` object, and the most
 straightforward (but not statically typed) solution to do what we want could
-be achieved like this::
+be achieved like this:
+
+::
 
     func _on_body_entered(body: Node2D) -> void:
         body.label.text = name  # Produces UNSAFE_PROPERTY_ACCESS warning.
@@ -490,7 +528,9 @@ be achieved like this::
 This piece of code produces an ``UNSAFE_PROPERTY_ACCESS`` warning because
 ``label`` is not defined in ``Node2D``. To solve this, we could first check if the
 ``label`` property exist and cast it to type ``Label`` before settings its text
-property like so::
+property like so:
+
+::
 
     func _on_body_entered(body: Node2D) -> void:
         if "label" in body:
@@ -501,7 +541,9 @@ However, this produces an ``UNSAFE_CAST`` warning because ``body.label`` is of a
 ``Object.get()`` method which returns the object as a ``Variant`` value or returns
 ``null`` if the property doesn't exist. You can then determine whether the
 property contains an object of the right type using the ``is`` keyword, and
-finally declare a statically typed variable with the object::
+finally declare a statically typed variable with the object:
+
+::
 
     func _on_body_entered(body: Node2D) -> void:
         var label_variant: Variant = body.get("label")
@@ -517,7 +559,9 @@ Cases where you can't specify types
 To wrap up this introduction, let's mention cases where you can't use type hints.
 This will trigger a **syntax error**.
 
-1. You can't specify the type of individual elements in an array or a dictionary::
+1. You can't specify the type of individual elements in an array or a dictionary:
+
+::
 
         var enemies: Array = [$Goblin: Enemy, $Zombie: Enemy]
         var character: Dictionary = {
@@ -526,7 +570,9 @@ This will trigger a **syntax error**.
             inventory: Inventory = $Inventory,
         }
 
-2. Nested types are not currently supported::
+2. Nested types are not currently supported:
+
+::
 
         var teams: Array[Array[Character]] = []
 

+ 33 - 11
tutorials/shaders/shader_reference/shader_functions.rst

@@ -1346,7 +1346,9 @@ Exponential and math function descriptions
     Performs smooth Hermite interpolation between ``0`` and ``1`` when a < c < b.
     This is useful in cases where a threshold function with a smooth transition is desired.
 
-    Smoothstep is equivalent to::
+    Smoothstep is equivalent to:
+
+    ::
 
         vec_type t;
         t = clamp((c - a) / (b - a), 0.0, 1.0);
@@ -1751,7 +1753,9 @@ vec3 **refract**\ (\ vec3 I, vec3 N, float eta) :ref:`🔗<shader_func_refract>`
 
     For a given incident vector ``I``, surface normal ``N`` and ratio of indices of refraction, ``eta``, refract returns the refraction vector, ``R``.
 
-    ``R`` is calculated as::
+    ``R`` is calculated as:
+
+    ::
 
         k = 1.0 - eta * eta * (1.0 - dot(N, I) * dot(N, I));
         if (k < 0.0)
@@ -2143,7 +2147,9 @@ bool **any**\ (\ |vec_bool_type| x) :ref:`🔗<shader_func_any>`
 
     Returns ``true`` if any element of a boolean vector is ``true``, ``false`` otherwise.
 
-    Functionally equivalent to::
+    Functionally equivalent to:
+
+    ::
 
         bool any(bvec x) {     // bvec can be bvec2, bvec3 or bvec4
             bool result = false;
@@ -2177,7 +2183,9 @@ bool **all**\ (\ |vec_bool_type| x) :ref:`🔗<shader_func_all>`
 
     Returns ``true`` if all elements of a boolean vector are ``true``, ``false`` otherwise.
 
-    Functionally equivalent to::
+    Functionally equivalent to:
+
+    ::
 
         bool all(bvec x)       // bvec can be bvec2, bvec3 or bvec4
         {
@@ -2594,7 +2602,9 @@ vec4 **textureLod**\ (\ samplerCubeArray s, vec4 p, float lod) :ref:`🔗<shader
 
     Performs a texture lookup at coordinate ``p`` from the texture bound to sampler with
     an explicit level-of-detail as specified in ``lod``. ``lod`` specifies λbase and sets the
-    partial derivatives as follows::
+    partial derivatives as follows:
+
+    ::
 
         δu/δx=0, δv/δx=0, δw/δx=0
         δu/δy=0, δv/δy=0, δw/δy=0
@@ -2815,7 +2825,9 @@ vec4 **textureGather**\ (\ samplerCube s, vec3 p [, int comps] ) :ref:`🔗<shad
 
     Gathers four texels from a texture.
 
-    Returns the value::
+    Returns the value:
+
+    ::
 
         vec4(Sample_i0_j1(p, base).comps,
              Sample_i1_j1(p, base).comps,
@@ -3258,7 +3270,9 @@ uint **packUnorm2x16**\ (\ vec2 v) :ref:`🔗<shader_func_packUnorm2x16>`
 
     Converts each component of the normalized floating-point value v into 16-bit integer values and then packs the results into a 32-bit unsigned integer.
 
-    The conversion for component c of ``v`` to fixed-point is performed as follows::
+    The conversion for component c of ``v`` to fixed-point is performed as follows:
+
+    ::
 
         round(clamp(c, 0.0, 1.0) * 65535.0)
 
@@ -3319,7 +3333,9 @@ uint **packSnorm2x16**\ (\ vec2 v) :ref:`🔗<shader_func_packSnorm2x16>`
 
     Convert each component of the normalized floating-point value ``v`` into 16-bit integer values and then packs the results into a 32-bit unsigned integer.
 
-    The conversion for component c of ``v`` to fixed-point is performed as follows::
+    The conversion for component c of ``v`` to fixed-point is performed as follows:
+
+    ::
 
         round(clamp(c, -1.0, 1.0) * 32767.0)
 
@@ -3379,7 +3395,9 @@ uint **packUnorm4x8**\ (\ vec4 v) :ref:`🔗<shader_func_packUnorm4x8>`
 
     Converts each component of the normalized floating-point value ``v`` into 16-bit integer values and then packs the results into a 32-bit unsigned integer.
 
-    The conversion for component c of ``v`` to fixed-point is performed as follows::
+    The conversion for component c of ``v`` to fixed-point is performed as follows:
+
+    ::
 
         round(clamp(c, 0.0, 1.0) * 255.0)
 
@@ -3440,7 +3458,9 @@ uint **packSnorm4x8**\ (\ vec4 v) :ref:`🔗<shader_func_packSnorm4x8>`
 
     Convert each component of the normalized floating-point value ``v`` into 16-bit integer values and then packs the results into a 32-bit unsigned integer.
 
-    The conversion for component c of ``v`` to fixed-point is performed as follows::
+    The conversion for component c of ``v`` to fixed-point is performed as follows:
+
+    ::
 
         round(clamp(c, -1.0, 1.0) * 127.0)
 
@@ -3954,7 +3974,9 @@ Bitwise function descriptions
 
     |componentwise|
 
-    Extracts ``x`` into a floating-point significand in the range ``[0.5, 1.0)`` and in integral exponent of two, such that::
+    Extracts ``x`` into a floating-point significand in the range ``[0.5, 1.0)`` and in integral exponent of two, such that:
+
+    ::
 
         x = significand * 2 ^ exponent
 

+ 3 - 1
tutorials/ui/bbcode_in_richtextlabel.rst

@@ -581,7 +581,9 @@ To handle clicked ``[url]`` tags, connect the ``RichTextLabel`` node's
 :ref:`meta_clicked <class_RichTextLabel_signal_meta_clicked>` signal to a script function.
 
 For example, the following method can be connected to ``meta_clicked`` to open
-clicked URLs using the user's default web browser::
+clicked URLs using the user's default web browser:
+
+::
 
     # This assumes RichTextLabel's `meta_clicked` signal was connected to
     # the function below using the signal connection dialog.