[stable] Merge commit godotengine/godot-docs@4b616e1

.github/workflows/build_offline_docs.yml

@@ -8,6 +8,9 @@ on:
 
 jobs:
   build:
+    # Don't run scheduled runs on forks unless the CI_OFFLINE_DOCS_CRON variable is set to 'true'.
+    # Manual runs can still be triggered as normal.
+    if: ${{ github.repository_owner == 'godotengine' || github.event_name != 'schedule' || vars.CI_OFFLINE_DOCS_CRON == 'true' }}
     runs-on: ubuntu-22.04
     strategy:
       matrix:

.github/workflows/ci.yml

@@ -10,23 +10,16 @@ concurrency:
 
 jobs:
   build:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Install dependencies
-        run: |
-          # Install tools used by `_tools/format.sh`.
-          sudo apt-get -qq update
-          sudo apt-get -qq install dos2unix recode
-          sudo pip3 install -r requirements.txt
-          sudo pip3 install codespell
+      - name: Style checks via pre-commit
+        uses: pre-commit/[email protected]
 
-      - name: Linter checks
-        run: |
-          bash _tools/format.sh
-          codespell -I _tools/codespell-ignore.txt -x _tools/codespell-ignore-lines.txt -S tutorials/i18n/locales.rst {about,community,contributing,getting_started,tutorials}/**/*.rst
+      - name: Install dependencies
+        run: sudo pip3 install -r requirements.txt
 
       - name: Migrate to Redot
         run: |

.github/workflows/sync_class_ref.yml

@@ -10,6 +10,9 @@ concurrency:
 
 jobs:
   build:
+    # Don't run scheduled runs on forks unless the CI_SYNC_CLASS_REF_CRON variable is set to 'true'.
+    # Manual runs can still be triggered as normal.
+    if: ${{ github.repository_owner == 'godotengine' || github.event_name != 'schedule' || vars.CI_SYNC_CLASS_REF_CRON == 'true' }}
     name: Update class reference files based on the engine revision
     runs-on: ubuntu-latest
     env:

.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+default_language_version:
+  python: python3
+
+repos:
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.3.0
+    hooks:
+      - id: codespell
+        files: ^(about|community|contributing|getting_started|tutorials)/.*\.rst$
+        additional_dependencies: [tomli]
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: fix-byte-order-marker
+      - id: mixed-line-ending
+        args: ['--fix=lf']

_templates/layout.html

@@ -13,16 +13,6 @@
 
 {% block linktags -%}
   <meta name="theme-color" content="#3d8fcc" />
-  {% if godot_inject_language_links -%}
-  {% for alternate_lang in godot_docs_supported_languages -%}
-  {# Convert to ISO 639-1 format, e.g. zh_CN -> zh-cn -#}
-  {% set alternate_lang_href = alternate_lang.lower().replace("_", "-") -%}
-  <link rel="alternate" hreflang="{{ alternate_lang_href }}" href="{{ godot_docs_basepath }}{{ alternate_lang }}/{{ godot_canonical_version }}/{{ pagename }}{{ godot_docs_suffix }}" />
-  {% endfor -%}
-  <link rel="alternate" hreflang="x-default" href="{{ godot_docs_basepath }}{{ godot_default_lang }}/{{ godot_canonical_version }}/{{ pagename }}{{ godot_docs_suffix }}" />
-
-  <link rel="canonical" href="{{ godot_docs_basepath }}{{ lang_attr }}/{{ godot_canonical_version }}/{{ pagename }}{{ godot_docs_suffix }}" />
-  {% endif -%}
   {{ super() }}
 {% endblock -%}
 

_tools/codespell-dict.txt

@@ -0,0 +1 @@
+anti-aliasing->antialiasing

about/docs_changelog.rst

@@ -13,6 +13,52 @@ added since version 3.0.
 .. note:: This document only contains new pages so not all changes are reflected,
           many pages have been substantially updated but are not reflected in this document.
 
+New pages since version 4.2
+---------------------------
+
+About
+^^^^^
+
+- :ref:`doc_system_requirements`
+
+2D
+^^
+
+- :ref:`doc_2d_parallax`
+
+Contributing
+^^^^^^^^^^^^
+
+- :ref:`doc_handling_compatibility_breakages`
+- :ref:`doc_ways_to_contribute`
+
+GDExtension
+^^^^^^^^^^^
+
+- :ref:`doc_gdextension_file`
+- :ref:`doc_gdextension_docs_system`
+
+Migrating
+^^^^^^^^^
+
+- :ref:`doc_upgrading_to_godot_4.3`
+
+Rendering
+^^^^^^^^^
+
+- :ref:`doc_compositor`
+
+XR
+^^
+
+- :ref:`doc_a_better_xr_start_script`
+- :ref:`doc_openxr_passthrough`
+- :ref:`doc_xr_next_steps`
+- :ref:`doc_openxr_settings`
+- :ref:`doc_openxr_composition_layers`
+- :ref:`doc_openxr_body_tracking`
+
+
 New pages since version 4.1
 ---------------------------
 

about/faq.rst

@@ -167,6 +167,38 @@ The main reasons for creating a custom scripting language for Godot were:
 
 GDScript was designed to curtail the issues above, and more.
 
+.. _doc_faq_which_programming_language_is_fastest:
+
+Which programming language is fastest?
+--------------------------------------
+
+In most games, the *scripting language* itself is not the cause of performance
+problems. Instead, performance is slowed by inefficient algorithms (which are
+slow in all languages), by GPU performance, or by the common C++ engine code
+like physics or navigation. All languages supported by Godot are fast enough for
+general-purpose scripting. You should choose a language based on other factors,
+like ease-of-use, familiarity, platform support, or language features.
+
+In general, the performance of C# and GDScript is within the same order of
+magnitude, and C++ is faster than both.
+
+Comparing GDScript performance to C# is tricky, since C# can be faster in some
+specific cases. The C# *language* itself tends to be faster than GDScript, which
+means that C# can be faster in situations with few calls to Godot engine code.
+However, C# can be slower than GDScript when making many Godot API calls, due
+to the cost of *marshalling*. C#'s performance can also be brought down by garbage
+collection which occurs at random and unpredictable moments. This can result in
+stuttering issues in complex projects, and is not exclusive to Godot.
+
+C++, using :ref:`GDExtension <doc_what_is_gdextension>`, will almost always be
+faster than either C# or GDScript. However, C++ is less easy to use than C# or
+GDScript, and is slower to develop with.
+
+You can also use multiple languages within a single project, with
+:ref:`cross-language scripting <doc_cross_language_scripting>`, or by using
+GDExtension and scripting languages together. Be aware that doing so comes with
+its own complications.
+
 What 3D model formats does Godot support?
 -----------------------------------------
 

about/list_of_features.rst

@@ -10,8 +10,8 @@ This page aims to list **all** features currently supported by Godot.
 .. note::
 
     This page lists features supported by the current stable version of
-    Godot. Some of these features may not be available in the
-    `LTS release series (3.x) <https://docs.godotengine.org/en/3.5/about/list_of_features.html>`__.
+    Godot. Some of these features are not available in the
+    `3.x release series <https://docs.godotengine.org/en/3.6/about/list_of_features.html>`__.
 
 Platforms
 ---------
@@ -30,8 +30,7 @@ Platforms
      on an old enough base distribution.
    - Official binaries are compiled using the
      `Godot Engine buildroot <https://github.com/godotengine/buildroot>`__,
-     allowing for binaries that work across common Linux distributions
-     (including LTS variants).
+     allowing for binaries that work across common Linux distributions.
 
 - Android (editor support is experimental).
 - :ref:`Web browsers <doc_using_the_web_editor>`. Experimental in 4.0,
@@ -367,7 +366,7 @@ Rendering
 - ETC2 (not supported on macOS).
 - S3TC (not supported on mobile/Web platforms).
 
-**Anti-aliasing:**
+**Antialiasing:**
 
 - Temporal :ref:`antialiasing <doc_3d_antialiasing>` (TAA).
 - AMD FidelityFX Super Resolution 2.2 :ref:`antialiasing <doc_3d_antialiasing>` (FSR2),
@@ -487,7 +486,7 @@ Scripting
    - Use any build system and language features you wish.
 
 - Actively developed GDExtension bindings for `D <https://github.com/godot-dlang/godot-dlang>`__,
-  `Haxe <https://hxgodot.github.io/>`__, `Swift <https://github.com/migueldeicaza/SwiftGodot>`__, and `Rust <https://github.com/godot-rust/gdextension>`__
+  `Swift <https://github.com/migueldeicaza/SwiftGodot>`__, and `Rust <https://github.com/godot-rust/gdextension>`__
   bindings provided by the community. (Some of these bindings may be experimental and not production-ready).
 
 Audio

community/asset_library/submitting_to_assetlib.rst

@@ -211,12 +211,6 @@ You can check all assets currently pending a review `here <https://godotengine.o
 The approval process is manual and may take up to a few days for your asset to be accepted (or rejected), so please
 be patient!
 
-.. note::
-
-    You may have some luck accelerating the approval process by messaging the
-    moderators and AssetLib reviewers on the `Godot Contributors Chat <https://chat.godotengine.org/>`_,
-    or the official Discord server.
-
 You will be informed when your asset is reviewed. If it was rejected,
 you will be told why that may have been, and you will be able to submit it again
 with the appropriate changes.

community/tutorials.rst

@@ -3,7 +3,10 @@
 Tutorials and resources
 =======================
 
-This is a list of third-party tutorials and resources created by the Godot community. For resources, remember that there is the official `Godot Asset Library <https://godotengine.org/asset-library/asset>`_ full of official and community resources too! Also, have a look at this `huge list over at Reddit <https://www.reddit.com/r/godot/comments/an0iq5/godot_tutorials_list_of_video_and_written/>`_.
+This is a list of third-party tutorials and resources created by the Godot
+community. For resources, remember that there is the official
+`Godot Asset Library <https://godotengine.org/asset-library/asset>`_ full of
+official and community resources too!
 
 Think there is something missing here? Feel free to submit a `Pull Request <https://github.com/godotengine/godot-docs/blob/master/community/tutorials.rst>`_ as always.
 

conf.py

@@ -9,7 +9,7 @@
 
 # -- General configuration ------------------------------------------------
 
-needs_sphinx = "1.3"
+needs_sphinx = "8.1"
 
 # Sphinx extension module names and templates location
 sys.path.append(os.path.abspath("_extensions"))
@@ -63,6 +63,9 @@
 
 # Specify the site name for the Open Graph extension.
 ogp_site_name = "Godot Engine documentation"
+ogp_social_cards = {
+    "enable": False
+}
 
 if not os.getenv("SPHINX_NO_GDSCRIPT"):
     extensions.append("gdscript")
@@ -158,7 +161,6 @@
 # -- Options for HTML output ----------------------------------------------
 
 html_theme = "sphinx_rtd_theme"
-html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 if on_rtd:
     using_rtd_theme = True
 
@@ -168,8 +170,11 @@
     "logo_only": True,
     # Collapse navigation (False makes it tree-like)
     "collapse_navigation": False,
-    # Hide the documentation version name/number under the logo
-    "display_version": False,
+    # Remove version and language picker beneath the title
+    "version_selector": False,
+    "language_selector": False,
+    # Set Flyout menu to attached
+    "flyout_display": "attached",
 }
 
 html_title = supported_languages[language] % ( "(" + version + ")" )
@@ -181,13 +186,9 @@
     "github_repo": "godot-docs",  # Repo name
     "github_version": "4.3",  # Version
     "conf_py_path": "/",  # Path in the checkout to the docs root
-    "godot_inject_language_links": True,
-    "godot_docs_supported_languages": list(supported_languages.keys()),
     "godot_docs_title": supported_languages[language],
     "godot_docs_basepath": "https://docs.godotengine.org/",
     "godot_docs_suffix": ".html",
-    "godot_default_lang": "en",
-    "godot_canonical_version": "stable",
     # Distinguish local development website from production website.
     # This prevents people from looking for changes on the production website after making local changes :)
     "godot_title_prefix": "" if on_rtd else "(DEV) ",
@@ -211,16 +212,14 @@
 # These paths are either relative to html_static_path
 # or fully qualified paths (e.g. https://...)
 html_css_files = [
-    'css/algolia.css',
-    'https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css',
-    "css/custom.css?10", # Increment the number at the end when the file changes to bust the cache.
+    "css/custom.css",
 ]
 
 if not on_rtd:
     html_css_files.append("css/dev.css")
 
 html_js_files = [
-    "js/custom.js?7", # Increment the number at the end when the file changes to bust the cache.
+    "js/custom.js",
 ]
 
 # Output file base name for HTML help builder

contributing/development/code_style_guidelines.rst

@@ -61,6 +61,8 @@ You need to use **clang-format 17** to be compatible with Godot's format. Later
 be suitable, but previous versions may not support all used options, or format
 some things differently, leading to style issues in pull requests.
 
+.. _doc_code_style_guidelines_pre_commit_hook:
+
 Pre-commit hook
 ^^^^^^^^^^^^^^^