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

Author: Calinou

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:
 

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
 

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
 

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
 

contributing/development/compiling/compiling_for_web.rst

@@ -34,21 +34,27 @@ 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
 
 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
 

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

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
 

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