Replace remaining uses of shorthand codeblock syntax, add CI check

Author: dalexeev

.github/workflows/ci.yml

@@ -19,6 +19,10 @@ jobs:
       - name: Style checks via pre-commit
         uses: pre-commit/action@v3.0.1
 
+      - name: Custom RST checks (check-rst.sh)
+        run: |
+          bash ./_tools/check-rst.sh
+
       - name: Get Python version
         id: pythonv
         run: |

_tools/check-rst.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+set -uo pipefail
+
+output=$(grep -r -P '^(?!\s*\.\.).*\S::$' --include='*.rst' --exclude='docs_writing_guidelines.rst' .)
+if [[ -n $output ]]; then
+  echo 'The shorthand codeblock syntax (trailing `::`) is not allowed.'
+  echo "$output"
+  exit 1
+fi

contributing/development/code_style_guidelines.rst

@@ -73,8 +73,8 @@ To set up:
 
 ::
 
-  pip install pre-commit
-  pre-commit install
+    pip install pre-commit
+    pre-commit install
 
 
 You can also run the hook manually with ``pre-commit run``.

contributing/development/compiling/compiling_for_linuxbsd.rst

@@ -314,12 +314,15 @@ And then use the ``--headless`` command line argument:
     ./bin/godot.linuxbsd.editor.x86_64 --headless
 
 To compile a debug *server* build which can be used with
-:ref:`remote debugging tools <doc_command_line_tutorial>`, use::
+:ref:`remote debugging tools <doc_command_line_tutorial>`, use:
+
+::
 
     scons platform=linuxbsd target=template_debug
 
-To compile a *server* build which is optimized to run dedicated game servers,
-use::
+To compile a *server* build which is optimized to run dedicated game servers, use:
+
+::
 
     scons platform=linuxbsd target=template_release production=yes
 
@@ -363,7 +366,7 @@ must be copied to:
 
 and named like this (even for \*BSD which is seen as "Linux/X11" by Godot):
 
-::
+.. code:: text
 
     linux_debug.arm32
     linux_debug.arm64
@@ -449,7 +452,7 @@ indicates to Clang the target architecture, and OS we want to build for.
 If all went well, you should now see a ``bin`` directory, and within it,
 a binary similar to the following:
 
-::
+.. code:: text
 
     godot.linuxbsd.editor.rv64.llvm
 
@@ -486,7 +489,7 @@ link-time optimization, making the resulting binaries smaller and faster.
 
 If this error occurs:
 
-::
+.. code:: text
 
     /usr/bin/ld: cannot find -l:libatomic.a: No such file or directory
 
@@ -517,7 +520,9 @@ repositories, so you will have to install its binaries manually.
     PATH="$HOME/.local/share/mold/bin:$PATH"
 
 - Open a new terminal (or run ``source "$HOME/.bash_profile"``),
-  then use the following SCons command when compiling Godot::
+  then use the following SCons command when compiling Godot:
+
+  ::
 
     scons platform=linuxbsd linker=mold
 

contributing/development/compiling/compiling_for_macos.rst

@@ -53,11 +53,15 @@ Compiling
 
 Start a terminal, go to the root directory of the engine source code.
 
-To compile for Intel (x86-64) powered Macs, use::
+To compile for Intel (x86-64) powered Macs, use:
+
+::
 
     scons platform=macos arch=x86_64
 
-To compile for Apple Silicon (ARM64) powered Macs, use::
+To compile for Apple Silicon (ARM64) powered Macs, use:
+
+::
 
     scons platform=macos arch=arm64
 
@@ -102,7 +106,9 @@ 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
 
 To create an ``.app`` bundle, you need to use the template located in ``misc/dist/macos_tools.app``. Typically, for an optimized
-editor binary built with ``dev_build=yes``::
+editor binary built with ``dev_build=yes``:
+
+::
 
     cp -r misc/dist/macos_tools.app ./bin/Godot.app
     mkdir -p bin/Godot.app/Contents/MacOS
@@ -116,7 +122,9 @@ editor binary built with ``dev_build=yes``::
     for the MoltenVK Vulkan portability library. By default, it will be linked
     statically from your installation of the Vulkan SDK for macOS.
     You can also choose to link it dynamically by passing ``use_volk=yes`` and
-    including the dynamic library in your ``.app`` bundle::
+    including the dynamic library in your ``.app`` bundle:
+
+    ::
 
         mkdir -p <Godot bundle name>.app/Contents/Frameworks
         cp <Vulkan SDK path>/macOS/lib/libMoltenVK.dylib <Godot bundle name>.app/Contents/Frameworks/libMoltenVK.dylib
@@ -138,12 +146,15 @@ And then use the ``--headless`` command line argument:
     ./bin/godot.macos.editor.x86_64 --headless
 
 To compile a debug *server* build which can be used with
-:ref:`remote debugging tools <doc_command_line_tutorial>`, use::
+:ref:`remote debugging tools <doc_command_line_tutorial>`, use:
+
+::
 
     scons platform=macos target=template_debug
 
-To compile a release *server* build which is optimized to run dedicated game servers,
-use::
+To compile a release *server* build which is optimized to run dedicated game servers, use:
+
+::
 
     scons platform=macos target=template_release production=yes
 
@@ -157,17 +168,21 @@ the editor: ``target=template_release`` (release template) and
 Official templates are *Universal 2* binaries which support both ARM64 and Intel
 x86_64 architectures.
 
-- To support ARM64 (Apple Silicon) + Intel x86_64::
+- To support ARM64 (Apple Silicon) + Intel x86_64:
 
-    scons platform=macos target=template_debug arch=arm64
-    scons platform=macos target=template_release arch=arm64
-    scons platform=macos target=template_debug arch=x86_64
-    scons platform=macos target=template_release arch=x86_64 generate_bundle=yes
+    ::
 
-- To support ARM64 (Apple Silicon) only (smaller file size, but less compatible with older hardware)::
+        scons platform=macos target=template_debug arch=arm64
+        scons platform=macos target=template_release arch=arm64
+        scons platform=macos target=template_debug arch=x86_64
+        scons platform=macos target=template_release arch=x86_64 generate_bundle=yes
 
-    scons platform=macos target=template_debug arch=arm64
-    scons platform=macos target=template_release arch=arm64 generate_bundle=yes
+- To support ARM64 (Apple Silicon) only (smaller file size, but less compatible with older hardware):
+
+    ::
+
+        scons platform=macos target=template_debug arch=arm64
+        scons platform=macos target=template_release arch=arm64 generate_bundle=yes
 
 To create an ``.app`` bundle like in the official builds, you need to use the
 template located in ``misc/dist/macos_template.app``. This process can be automated by using
@@ -181,7 +196,9 @@ an *Universal 2* binary from two separate ARM64 and x86_64 binaries (if both wer
     library. By default, it will be linked statically from your installation of
     the Vulkan SDK for macOS. You can also choose to link it dynamically by
     passing ``use_volk=yes`` and including the dynamic library in your ``.app``
-    bundle::
+    bundle:
+
+    ::
 
         mkdir -p macos_template.app/Contents/Frameworks
         cp <Vulkan SDK path>/macOS/libs/libMoltenVK.dylib macos_template.app/Contents/Frameworks/libMoltenVK.dylib
@@ -206,8 +223,9 @@ Windows using the Windows Subsystem for Linux). For that, you'll need to install
 as a target. First, follow the instructions to install it:
 
 Clone the `OSXCross repository <https://github.com/tpoechtrager/osxcross>`__
-somewhere on your machine (or download a ZIP file and extract it somewhere),
-e.g.::
+somewhere on your machine (or download a ZIP file and extract it somewhere), e.g.:
+
+::
 
     git clone --depth=1 https://github.com/tpoechtrager/osxcross.git "$HOME/osxcross"
 
@@ -218,7 +236,9 @@ e.g.::
 
 After that, you will need to define the ``OSXCROSS_ROOT`` as the path to
 the OSXCross installation (the same place where you cloned the
-repository/extracted the zip), e.g.::
+repository/extracted the zip), e.g.:
+
+::
 
     export OSXCROSS_ROOT="$HOME/osxcross"
 
@@ -228,7 +248,9 @@ Now you can compile with SCons like you normally would:
 
     scons platform=macos
 
-If you have an OSXCross SDK version different from the one expected by the SCons buildsystem, you can specify a custom one with the ``osxcross_sdk`` argument::
+If you have an OSXCross SDK version different from the one expected by the SCons buildsystem, you can specify a custom one with the ``osxcross_sdk`` argument:
+
+::
 
     scons platform=macos osxcross_sdk=darwin15
 
@@ -242,7 +264,7 @@ If you get a compilation error of this form early on, it's likely because
 the Xcode command line tools installation needs to be repaired after
 a macOS or Xcode update:
 
-::
+.. code:: text
 
     ./core/typedefs.h:45:10: fatal error: 'cstdint' file not found
     45 | #include <cstdint>

contributing/development/compiling/compiling_for_windows.rst

@@ -301,9 +301,11 @@ By default, Godot is built with dynamically linked ANGLE, you can use it by plac
 To compile Godot with statically linked ANGLE:
 
 - Download pre-built static libraries from `godot-angle-static library <https://github.com/godotengine/godot-angle-static/releases>`_, and unzip them.
-- When building Godot, add ``angle_libs={path}`` to tell SCons where to look for the ANGLE libraries::
+- When building Godot, add ``angle_libs={path}`` to tell SCons where to look for the ANGLE libraries:
 
-    scons platform=windows angle_libs=<...>
+    ::
+
+        scons platform=windows angle_libs=<...>
 
 .. note:: You can optionally build the godot-angle-static libraries yourself with
           the following steps:
@@ -414,7 +416,9 @@ Where ``/path/to/mingw`` is the path containing the ``bin`` directory where
 
 To make sure you are doing things correctly, executing the following in
 the shell should result in a working compiler (the version output may
-differ based on your system)::
+differ based on your system):
+
+::
 
     ${MINGW_PREFIX}/bin/x86_64-w64-mingw32-gcc --version
     # x86_64-w64-mingw32-gcc (GCC) 13.2.0
@@ -432,15 +436,18 @@ Cross-compiling from some Ubuntu versions may lead to
 `this bug <https://github.com/godotengine/godot/issues/9258>`_,
 due to a default configuration lacking support for POSIX threading.
 
-You can change that configuration following those instructions,
-for 64-bit::
+You can change that configuration following those instructions, for 64-bit:
+
+::
 
     sudo update-alternatives --config x86_64-w64-mingw32-gcc
     <choose x86_64-w64-mingw32-gcc-posix from the list>
     sudo update-alternatives --config x86_64-w64-mingw32-g++
     <choose x86_64-w64-mingw32-g++-posix from the list>
 
-And for 32-bit::
+And for 32-bit:
+
+::
 
     sudo update-alternatives --config i686-w64-mingw32-gcc
     <choose i686-w64-mingw32-gcc-posix from the list>

contributing/development/compiling/compiling_with_dotnet.rst

@@ -64,7 +64,9 @@ Building the managed libraries
 ------------------------------
 
 Once you have generated the .NET glue, you can build the managed libraries with
-the ``build_assemblies.py`` script::
+the ``build_assemblies.py`` script:
+
+::
 
     ./modules/mono/build_scripts/build_assemblies.py --godot-output-dir=./bin
 

contributing/development/compiling/getting_source.rst

@@ -40,7 +40,9 @@ and click on the link for the release you want.
 You can then download and extract the source from the download link on the page.
 
 With ``git``, you can also clone a stable release by specifying its branch or tag
-after the ``--branch`` (or just ``-b``) argument::
+after the ``--branch`` (or just ``-b``) argument:
+
+::
 
     # Clone the continuously maintained stable branch (`4.4` as of writing).
     git clone https://github.com/godotengine/godot.git -b 4.4

contributing/development/compiling/introduction_to_the_buildsystem.rst

@@ -52,7 +52,9 @@ SCons setup is configured to use all CPU threads but one (to keep the system res
 compilation). If you want to adjust how many CPU threads SCons will use, use the ``-j <threads>``
 parameter to specify how many threads will be used for the build.
 
-Example for using 4 threads::
+Example for using 4 threads:
+
+::
 
     scons -j4
 
@@ -68,7 +70,9 @@ SCons is invoked by just calling ``scons``. If no platform is specified,
 SCons will detect the target platform automatically based on the host platform.
 It will then start building for the target platform right away.
 
-To list the available target platforms, use ``scons platform=list``::
+To list the available target platforms, use ``scons platform=list``:
+
+.. code:: text
 
     scons platform=list
     scons: Reading SConscript files ...

contributing/documentation/editor_and_docs_localization.rst

@@ -217,29 +217,33 @@ The editor translations originate from C++ strings, and may use:
   placed in your translation where necessary for it to be meaningful after
   substitution. You may need to refer to the source string location to
   understand what kind of content will be substituted if it's not clear from the
-  sentence. Example (``%s``  will be substituted with a file name or path)::
+  sentence. Example (``%s``  will be substituted with a file name or path):
 
-    # PO file:
-    "There is no '%s' file."
+    ::
 
-    # Weblate:
-    There is no '%s' file.
+        # PO file:
+        "There is no '%s' file."
+
+        # Weblate:
+        There is no '%s' file.
 
 - **C escape characters** such as ``\n`` (line break) or ``\t`` (tabulation). In
   the Weblate editor, the ``\n`` characters are replaced by ``↵`` (return) and
   ``\t`` by ``↹``. Tabs are not used much, but you should make sure to use line
   breaks in the same way as the original English string (Weblate will issue a
   warning if you don't). Line breaks might sometimes be used for vertical
   spacing, or manual wrapping of long lines which would otherwise be too long
-  especially in the editor translation). Example::
+  especially in the editor translation). Example:
+
+    ::
 
-    # PO file:
-    "Scene '%s' is currently being edited.\n"
-    "Changes will only take effect when reloaded."
+        # PO file:
+        "Scene '%s' is currently being edited.\n"
+        "Changes will only take effect when reloaded."
 
-    # Weblate:
-    Scene '%s' is currently being edited.↵
-    Changes will only take effect when reloaded.
+        # Weblate:
+        Scene '%s' is currently being edited.↵
+        Changes will only take effect when reloaded.
 
 .. note::
   Only logical order of the characters matters, in the right-to-left text, format
@@ -307,7 +311,9 @@ Some of the tags used are from the original BBCode (e.g. ``[b]Bold[/b]`` and
 ``[i]Italics[/i]``), while others are Godot-specific and used for advanced
 features such as inline code (e.g. ``[code]true[/code]``), linking to another
 class (e.g. ``[Node2D]``) or to a property in a given class (e.g.
-``[member Node2D.position]``), or for multiline code blocks. Example::
+``[member Node2D.position]``), or for multiline code blocks. Example:
+
+::
 
     Returns a color according to the standardized [code]name[/code] with [code]alpha[/code] ranging from 0 to 1.
     [codeblock]