Merge pull request #9582 from russellsanborn/comma-before-but

Add commas before "but" throughout documentation

contributing/development/best_practices_for_engine_contributors.rst

@@ -167,7 +167,7 @@ who design software) to actually understand all future user needs. Trying to
 write very flexible structures that cater to many use cases at once is often a
 mistake.
 
-We may come up with something we believe is brilliant but later find out that
+We may come up with something we believe is brilliant, but later find out that
 users will never even use half of it or that they require features that don't
 quite fit into our original design, forcing us to either throw it away
 or make it even more complex.

contributing/development/code_style_guidelines.rst

@@ -35,7 +35,7 @@ fine. If you plan to contribute regularly, however, we strongly advise that you
 set up clang-format locally to check and automatically fix all your commits.
 
 .. warning:: Godot's code style should *not* be applied to third-party code,
-             i.e. that is included in Godot's source tree but was not written
+             i.e. code that is included in Godot's source tree, but was not written
              specifically for our project. Such code usually comes from
              different upstream projects with their own style guides (or lack
              thereof), and don't want to introduce differences that would make
@@ -65,7 +65,7 @@ Pre-commit hook
 ^^^^^^^^^^^^^^^
 
 For ease of use, we provide hooks for Git with the `pre-commit <https://pre-commit.com/>`__
-Python framework that will run clang-format automatically on all your commits with the 
+Python framework that will run clang-format automatically on all your commits with the
 correct version of clang-format.
 To set up:
 
@@ -77,7 +77,7 @@ To set up:
 
 You can also run the hook manually with ``pre-commit run``.
 
-.. note:: 
+.. note::
 
     Previously, we supplied a hook in the folder ``misc/hooks``. If you copied the
     script manually, these hooks should still work, but symlinks will be broken.
@@ -382,7 +382,7 @@ instead.
         // ...
     }
 
-For member variables, don't use Javadoc-style comments but use single-line comments instead:
+For member variables, don't use Javadoc-style comments, but use single-line comments instead:
 
 .. code-block:: cpp
 

contributing/development/compiling/introduction_to_the_buildsystem.rst

@@ -403,7 +403,7 @@ To perform an SCU build, use the ``scu_build=yes`` SCons option.
           regular build prior to submitting the PR. This is because SCU builds
           by nature include headers from earlier ``.cpp`` files in the
           translation unit, therefore won't catch all the includes you will
-          need in a regular build. The CI will catch these errors but it will
+          need in a regular build. The CI will catch these errors, but it will
           usually be faster to catch them on a local build on your machine.
 
 Export templates

contributing/documentation/building_the_manual.rst

@@ -120,7 +120,7 @@ If you run into errors, you may try the following command:
 
 If you get a ``MemoryError`` or ``EOFError``, you can remove the ``classes/`` folder and
 run ``make`` again.
-This will drop the class references from the final HTML documentation but will keep the
+This will drop the class references from the final HTML documentation, but will keep the
 rest intact.
 
 .. important::

contributing/documentation/contributing_to_the_documentation.rst

@@ -89,7 +89,7 @@ and to log in to use it. Once logged in, you can propose change like so:
 
 4. At the bottom of the web page, summarize the changes you made and click the
    button **Propose file change**. Make sure to replace the placeholder "Update file.rst"
-   by a short but clear one-line description, as this is the commit title.
+   by a short, but clear one-line description, as this is the commit title.
 
 5. On the following screens, click the **Create pull request** button until you
    see a message like *Username wants to merge 1 commit into godotengine:master

contributing/workflow/pr_review_guidelines.rst

@@ -12,7 +12,7 @@ Pull request review process
     wanting to know how to ensure that their PR is merged.
 
 From a high level, the ideal life cycle of a pull request looks like the
-following: 
+following:
 
   1. A contributor opens a PR that fixes a specific problem (optimally closing
      a GitHub `issue <https://github.com/godotengine/godot>`_ or implementing
@@ -33,9 +33,9 @@ following:
 
 This document will explain steps 2, 3, 4, and 5 in more detail. For a more
 detailed explanation of the pull request workflow please see the :ref:`pull
-request workflow document <doc_pr_workflow>`. 
+request workflow document <doc_pr_workflow>`.
 
-.. note:: 
+.. note::
   In practice these steps may blend together. Oftentimes maintainers will
   provide comments on code style and code quality at the same time and will
   approve a pull request for both.
@@ -160,7 +160,7 @@ As you review pull requests, keep the Godot `Code of Conduct
 
 * Always assume positive intent from others.
 
-* Feedback is always welcome but keep your criticism constructive.
+* Feedback is always welcome, but keep your criticism constructive.
 
 Here are some things to avoid as you iterate on a pull request with a
 contributor:
@@ -178,7 +178,7 @@ contributor:
   areas and in performance-sensitive areas than it is in editor code for
   example.
 
-* **Expanding the scope of a pull request.** 
+* **Expanding the scope of a pull request.**
 
   Providing context or related/similar issues or proposals that may be fixed
   similarly can be helpful, but adding a "may as well fix that thing over there
@@ -253,7 +253,7 @@ Merging pull requests
 In general, pull requests should only be merged by members of the production
 team or team leaders for pull requests in their area of the engine. For example,
 the networking team leader could merge a networking pull request that doesn't
-substantially change non-networking sections of code. 
+substantially change non-networking sections of code.
 
 In practice it is best to wait for a member of the production team to merge the
 pull request as they keep a close eye on the entire codebase and will likely
@@ -275,7 +275,7 @@ steps yourself.
 Production team members should ensure that the right people look at a pull
 request before it is merged. In some cases this may require multiple people to
 weigh in. In other cases, only one substantive approval is needed before the
-code can be merged. 
+code can be merged.
 
 In general, try not to merge things based on one review alone, especially if it
 is your own. Get a second opinion from another maintainer, and make sure all the

tutorials/2d/2d_sprite_animation.rst

@@ -271,7 +271,7 @@ released.
           it's important to keep in mind that ``play()`` isn't applied instantly.
           Instead, it's applied the next time the :ref:`AnimationPlayer <class_AnimationPlayer>` is processed.
           This may end up being on the next frame, causing a 'glitch' frame,
-          where the property change was applied but the animation was not.
+          where the property change was applied, but the animation was not.
           If this turns out to be a problem, after calling ``play()``, you can call ``advance(0)``
           to update the animation immediately.
 

tutorials/2d/2d_transforms.rst

@@ -45,7 +45,7 @@ resizing or stretching the screen. This transform is used internally (as
 described in :ref:`doc_multiple_resolutions`), but can also be manually set
 on each viewport.
 
-Input events are multiplied by this transform but lack the ones above. To
+Input events are multiplied by this transform, but lack the ones above. To
 convert InputEvent coordinates to local CanvasItem coordinates, the
 :ref:`CanvasItem.make_input_local() <class_CanvasItem_method_make_input_local>`
 function was added for convenience.

tutorials/3d/environment_and_post_processing.rst

@@ -499,7 +499,7 @@ own, the effect may not be that noticeable, which is intended.
 Instead, :abbr:`SSIL (Screen-Space Indirect Lighting)` is meant to be used as a
 *complement* to other global illumination techniques such as VoxelGI, SDFGI and
 LightmapGI. :abbr:`SSIL (Screen-Space Indirect Lighting)` also provides
-a subtle ambient occlusion effect, similar to SSAO but with less detail.
+a subtle ambient occlusion effect, similar to SSAO, but with less detail.
 
 This feature only provides indirect lighting. It is not a full global illumination
 solution. This makes it different from screen-space global illumination (SSGI)

tutorials/3d/lights_and_shadows.rst

@@ -160,12 +160,12 @@ at the cost of decreased performance.
     all" settings. To achieve the best visuals, you may need to use different
     shadow bias values on a per-light basis.
 
-**Note on Appearance Changes**: When enabling shadows on a light, be aware that the light's 
-appearance might change compared to when it's rendered without shadows in the compatibility 
-renderer. Due to limitations with older mobile devices, shadows are implemented using a multi-pass 
-rendering approach so lights with shadows are rendered in sRGB space instead of linear space. 
-This change in rendering space can sometimes drastically alter the light's appearance. To achieve a similar 
-appearance to an unshadowed light, you may need to adjust the light's energy setting. 
+**Note on Appearance Changes**: When enabling shadows on a light, be aware that the light's
+appearance might change compared to when it's rendered without shadows in the compatibility
+renderer. Due to limitations with older mobile devices, shadows are implemented using a multi-pass
+rendering approach so lights with shadows are rendered in sRGB space instead of linear space.
+This change in rendering space can sometimes drastically alter the light's appearance. To achieve a similar
+appearance to an unshadowed light, you may need to adjust the light's energy setting.
 
 Directional light
 -----------------
@@ -208,10 +208,10 @@ receive low-resolution shadows that may appear blocky.
 To fix this, a technique named *Parallel Split Shadow Maps* (PSSM) is used.
 This splits the view frustum in 2 or 4 areas. Each area gets its own shadow map.
 This allows small areas close to the viewer to have the same shadow resolution
-as a huge, far-away area. When shadows are enabled for DirectionalLight3D, the 
-default shadow mode is PSSM with 4 splits. In scenarios where an object is large 
-enough to appear in all four splits, it results in increased draw calls. Specifically, 
-such an object will be rendered five times in total: once for each of the four shadow 
+as a huge, far-away area. When shadows are enabled for DirectionalLight3D, the
+default shadow mode is PSSM with 4 splits. In scenarios where an object is large
+enough to appear in all four splits, it results in increased draw calls. Specifically,
+such an object will be rendered five times in total: once for each of the four shadow
 splits and once for the final scene rendering. This can impact performance, understanding
 this behavior is important for optimizing your scene and managing performance expectations.
 
@@ -535,7 +535,7 @@ not use mipmaps, which makes them faster to render. However, projectors will
 look grainy at distance. **Nearest/Linear Mipmaps** will look smoother at a
 distance, but projectors will look blurry when viewed from oblique angles. This
 can be resolved by using **Nearest/Linear Mipmaps Anisotropic**, which is the
-highest-quality mode but also the most expensive.
+highest-quality mode, but also the most expensive.
 
 If your project has a pixel art style, consider setting the filter to one of the
 **Nearest** values so that projectors use nearest-neighbor filtering. Otherwise,

tutorials/3d/mesh_lod.rst

@@ -148,14 +148,14 @@ independently from other viewports.
 The default mesh LOD threshold of 1 pixel is tuned to look *perceptually*
 lossless; it provides a significant performance gain with an unnoticeable loss
 in quality. Higher values will make LOD transitions happen sooner when the
-camera moves away, resulting in higher performance but lower quality.
+camera moves away, resulting in higher performance, but lower quality.
 
 If you need to perform per-object adjustments to mesh LOD, you can adjust how
 aggressive LOD transitions should be by adjusting the **LOD Bias** property on
 any node that inherits from GeometryInstance3D. Values *above* ``1.0`` will make
-LOD transitions happen later than usual (resulting in higher quality but lower
+LOD transitions happen later than usual (resulting in higher quality, but lower
 performance). Values *below* ``1.0`` will make LOD transitions happen sooner than
-usual (resulting in lower quality but higher performance).
+usual (resulting in lower quality, but higher performance).
 
 Additionally, ReflectionProbe nodes have their own **Mesh LOD Threshold** property
 that can be adjusted to improve rendering performance when the reflection probe

tutorials/3d/using_decals.rst

@@ -240,7 +240,7 @@ textures should be filtered. **Nearest/Linear** does not use mipmaps. However,
 decals will look grainy at a distance. **Nearest/Linear Mipmaps** will look
 smoother at a distance, but decals will look blurry when viewed from oblique
 angles. This can be resolved by using **Nearest/Linear Mipmaps Anisotropic**,
-which provides the highest quality but is also slower to render.
+which provides the highest quality, but is also slower to render.
 
 If your project has a pixel art style, consider setting the filter to one of the
 **Nearest** values so that decals use nearest-neighbor filtering. Otherwise,

tutorials/3d/variable_rate_shading.rst

@@ -37,12 +37,12 @@ density map linked at the bottom of this page:
 
 .. figure:: img/variable_rate_shading_textured_enabled.webp
    :align: center
-   :alt: Variable rate shading enabled in textured scene (lower quality but higher performance)
+   :alt: Variable rate shading enabled in textured scene (lower quality, but higher performance)
 
-   Variable rate shading enabled in textured scene (lower quality but higher performance)
+   Variable rate shading enabled in textured scene (lower quality, but higher performance)
 
 When used in scenes with low-frequency detail (such as scenes with a
-stylized/low-poly aesthetic), it's possible to achieve similar performance gains
+stylized/low-poly aesthetic), it's possible to achieve similar performance gains,
 but with less reduction in visual quality:
 
 .. figure:: img/variable_rate_shading_untextured_disabled.webp
@@ -53,9 +53,9 @@ but with less reduction in visual quality:
 
 .. figure:: img/variable_rate_shading_untextured_enabled.webp
    :align: center
-   :alt: Variable rate shading enabled in untextured scene (lower quality but higher performance)
+   :alt: Variable rate shading enabled in untextured scene (lower quality, but higher performance)
 
-   Variable rate shading enabled in untextured scene (lower quality but higher performance)
+   Variable rate shading enabled in untextured scene (lower quality, but higher performance)
 
 Hardware support
 ----------------

tutorials/3d/visibility_ranges.rst

@@ -15,7 +15,7 @@ On this page, you'll learn:
 
 .. seealso::
 
-    If you only need meshes to become less detailed over distance but don't have
+    If you only need meshes to become less detailed over distance, but don't have
     manually authored LOD meshes, consider relying on automatic
     :ref:`doc_mesh_lod` instead.
 

tutorials/3d/volumetric_fog.rst

@@ -142,11 +142,11 @@ and quality:
   for better performance.
 - **Rendering > Environment > Volumetric Fog > Volume Depth:** Number of slices
   to use along the depth of the froxel buffer for volumetric fog. A lower number
-  will be more efficient but may result in artifacts appearing during camera
+  will be more efficient, but may result in artifacts appearing during camera
   movement.
 - **Rendering > Environment > Volumetric Fog > Use Filter:** Enables filtering
   of the volumetric fog effect prior to integration. This substantially blurs
-  the fog which reduces fine details but also smooths out harsh edges and
+  the fog which reduces fine details, but also smooths out harsh edges and
   aliasing artifacts. Disable when more detail is required.
 
 .. note::
@@ -159,7 +159,7 @@ Using fog volumes for local volumetric fog
 ------------------------------------------
 
 Sometimes, you want fog to be constrained to specific areas. Conversely, you may
-want to have global volumetric fog but fog should be excluded from certain
+want to have global volumetric fog, but fog should be excluded from certain
 areas. Both approaches can be followed using FogVolume nodes.
 
 Here's a quick start guide to using FogVolumes:

tutorials/troubleshooting.rst

@@ -25,11 +25,11 @@ There are several ways to improve performance and battery life:
   which can be up to 4 times faster.
 - Open the Editor Settings and increase the value of **Low Processor Mode Sleep (µsec)**
   to ``33000`` (30 FPS). This value determines the amount of *microseconds*
-  between frames to render. Higher values will make the editor feel less reactive
+  between frames to render. Higher values will make the editor feel less reactive,
   but will help decrease CPU and GPU usage significantly.
 - If you have a node that causes the editor to redraw continuously (such as
   particles), hide it and show it using a script in the ``_ready()`` method.
-  This way, it will be hidden in the editor but will still be visible in the
+  This way, it will be hidden in the editor, but will still be visible in the
   running project.
 
 The editor stutters and flickers on my variable refresh rate monitor (G-Sync/FreeSync)
@@ -49,7 +49,7 @@ There are several workarounds for this:
   alleviate this, you can increase **Low Processor Mode Sleep (µsec)** to
   ``33000`` (30 FPS) in the Editor Settings. This value determines the amount of
   *microseconds* between frames to render. Higher values will make the editor
-  feel less reactive but will help decrease CPU and GPU usage significantly.
+  feel less reactive, but will help decrease CPU and GPU usage significantly.
 - Alternatively, disable variable refresh rate on your monitor or in the graphics driver.
 - VRR flicker can be reduced on some displays using the **VRR Control** or
   **Fine Tune Dark Areas** options in your monitor's OSD. These options may