Merge pull request #95 from Spartan322/merge/d8fecf7

Merge commit godotengine/godot-docs@d8fecf7

.github/dependabot.yml

@@ -9,5 +9,7 @@ updates:
     schedule:
       interval: "daily"
     ignore:
-      # ReadTheDocs is staying on v1.
+      # We need to decide on when we upgrade Sphinx manually,
+      # as historically, this has been proven to often imply larger changes
+      # (RTD compat, upgrading extensions, other dependencies, our content, etc.).
       - dependency-name: "sphinx"

.github/workflows/build_offline_docs.yml

@@ -11,27 +11,51 @@ jobs:
     # 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
+    runs-on: ubuntu-24.04
+    timeout-minutes: 180
     strategy:
       matrix:
         branch:
           - master
           - stable
+    permissions:
+      contents: write
     steps:
       - uses: actions/checkout@v4
         with:
           ref: ${{ matrix.branch }}
 
+      - name: Get Python version
+        id: pythonv
+        run: |
+          echo "PYTHON_VERSION=$(python --version)" >> $GITHUB_OUTPUT
+
+      - name: Restore cached virtualenv
+        uses: actions/cache/restore@v4
+        with:
+          key: venv-${{ runner.os }}-${{ steps.pythonv.outputs.PYTHON_VERSION }}-${{ hashFiles('requirements.txt') }}
+          path: .venv
+
       - name: Install dependencies
         run: |
-          sudo pip3 install -r requirements.txt
+          python -m venv .venv
+          source .venv/bin/activate
+          python -m pip install -r requirements.txt
+          echo "$VIRTUAL_ENV/bin" >> $GITHUB_PATH
+          echo "VIRTUAL_ENV=$VIRTUAL_ENV" >> $GITHUB_ENV
           sudo apt update
           sudo apt install parallel libwebp7
 
       - name: Migrate to Redot
         run: |
           python migrate.py . _migrated
   
+      - name: Save virtualenv cache
+        uses: actions/cache/save@v4
+        with:
+          key: venv-${{ runner.os }}-${{ steps.pythonv.outputs.PYTHON_VERSION }}-${{ hashFiles('requirements.txt') }}
+          path: .venv
+
       - name: Sphinx - Build HTML
         run: make SPHINXOPTS='--color -j 4' SPHINXSOURCEDIR='./_migrated' html
 

.github/workflows/cherrypick.yml

@@ -0,0 +1,75 @@
+name: Create Cherrypick PR
+
+on:
+  pull_request:
+      types:
+        - closed
+      branches:
+        # TODO: Extract this to an env variable?
+        - 'master'
+
+env:
+  # TODO: Add a way to handle multiple potential cherrypick targets.
+  TARGET_BRANCH: '4.3'
+  USERNAME: 'Godot Organization'
+  EMAIL: 'noreply@godotengine.org'
+
+jobs:
+  Create-cherrypick-PR:
+    # The cherrypick label is hardcoded because `contains()` doesn't seem to be able to use an environment variable as a second argument.
+    if: ${{ github.event.pull_request.merged == true && contains( github.event.pull_request.labels.*.name, 'cherrypick:4.3' ) }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    env:
+      # "Ternary" hack featured in the official docs.
+      # When using "Squash and merge", the commit hash is the last merge commit of the pull request merge branch.
+      # When using "Merge", the commit hash is the last commit to the head branch of the pull request.
+      # This is mildly error-prone, since in theory we could merge multiple commits without squashing.
+      # We are relying on human review of the generated PRs to catch that.
+      COMMIT_HASH: ${{ github.event.pull_request.commits > 1 && github.sha || github.event.pull_request.head.sha }}
+      PR_NUMBER: ${{ github.event.number }}
+
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+      with:
+        ref: ${{ env.TARGET_BRANCH }}
+
+    - name: Cherrypick Commit
+      id: cherrypick_commit
+      continue-on-error: true
+      # TODO: Maybe only fetch some branches?
+      run: |
+        git config user.name "${{ env.USERNAME }}"
+        git config user.email "${{ env.EMAIL }}"
+        git fetch
+        git cherry-pick -m 1 ${{ env.COMMIT_HASH }}
+
+    - name: Create Pull Request
+      if: steps.cherrypick_commit.outcome == 'success'
+      uses: peter-evans/create-pull-request@v7
+      with:
+        commit-message: 'Cherrypick to ${{ env.TARGET_BRANCH }}'
+        branch: 'cherrypick-${{ env.PR_NUMBER }}-${{ env.TARGET_BRANCH }}'
+        delete-branch: true
+
+        # Configure the commit author.
+        author: '${{ env.USERNAME }} <${{ env.EMAIL }}>'
+        committer: '${{ env.USERNAME }} <${{ env.EMAIL }}>'
+
+        # Configure the pull request.
+        title: 'Cherrypick ${{ env.PR_NUMBER }} to ${{ env.TARGET_BRANCH }}'
+        body: 'Cherrypick #${{ env.PR_NUMBER }} to ${{ env.TARGET_BRANCH }}.'
+        # TODO: Only add the bug or enhancement label, depending on which the original PR uses.
+        labels: 'bug,enhancement'
+
+    - name: Handle failure
+      if: steps.cherrypick_commit.outcome == 'failure'
+      run: |
+        echo "Can't automatically cherrypick. Potential causes:"
+        echo "- PR has multiple commits. Did you squash and merge?"
+        echo "- Cherrypick did not apply cleanly and can't be auto-merged."

.github/workflows/ci.yml

@@ -5,26 +5,51 @@ on:
   pull_request:
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref_name }}
   cancel-in-progress: true
 
 jobs:
   build:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
+    timeout-minutes: 120
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
       - name: Style checks via pre-commit
         uses: pre-commit/action@v3.0.1
 
+      - name: Get Python version
+        id: pythonv
+        run: |
+          echo "PYTHON_VERSION=$(python --version)" >> $GITHUB_OUTPUT
+
+      - name: Restore cached virtualenv
+        uses: actions/cache/restore@v4
+        with:
+          key: venv-${{ runner.os }}-${{ steps.pythonv.outputs.PYTHON_VERSION }}-${{ hashFiles('requirements.txt') }}
+          path: .venv
+
       - name: Install dependencies
-        run: sudo pip3 install -r requirements.txt
+        run: |
+          python -m venv .venv
+          source .venv/bin/activate
+          python -m pip install -r requirements.txt
+          echo "$VIRTUAL_ENV/bin" >> $GITHUB_PATH
+          echo "VIRTUAL_ENV=$VIRTUAL_ENV" >> $GITHUB_ENV
+
+      - name: Save virtualenv cache
+        uses: actions/cache/save@v4
+        with:
+          key: venv-${{ runner.os }}-${{ steps.pythonv.outputs.PYTHON_VERSION }}-${{ hashFiles('requirements.txt') }}
+          path: .venv
 
       - name: Migrate to Redot
         run: |
           python migrate.py . _migrated
 
       # Use dummy builder to improve performance as we don't need the generated HTML in this workflow.
       - name: Sphinx build
-        run: make SPHINXOPTS='--color -W -j 4' SPHINXSOURCEDIR='./_migrated' dummy
+        run: |
+          source .venv/bin/activate
+          make SPHINXOPTS='--color -W -j 4' SPHINXSOURCEDIR='./_migrated' dummy

.github/workflows/sync_class_ref.yml

@@ -3,14 +3,15 @@ name: Sync Class Reference
 on:
   workflow_dispatch:
   # Scheduled updates only run on the default/master branch.
+  # Other branches need to be run manually (usually after a new release for that branch).
   schedule:
-    # Run it at night (European time) every Saturday.
-    # The offset is there to try and avoid the high load times.
+    # Run it at (European) night time every Saturday.
+    # The offset is there to try and avoid high load times.
     - cron: '15 3 * * 6'
 
 # Make sure jobs cannot overlap.
 concurrency:
-  group: classref-sync-ci-master
+  group: classref-sync-ci-${{ github.ref_name }}
   cancel-in-progress: true
 
 jobs:
@@ -19,13 +20,14 @@ jobs:
     # 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
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
     env:
       engine_rev: 'master'
     permissions:
       contents: write
       pull-requests: write
-    
+
     steps:
       - name: Checkout the documentation repository
         uses: actions/checkout@v4

_extensions/gdscript.py

@@ -428,6 +428,8 @@ def innerstring_rules(ttype):
                         "@static_unload",
                         "@tool",
                         "@warning_ignore",
+                        "@warning_ignore_restore",
+                        "@warning_ignore_start",
                     ),
                     prefix=r"(?<!\.)",
                     suffix=r"\b",

_templates/layout.html

@@ -52,6 +52,16 @@
 
 {% if (not meta or meta.get('allow_comments') != 'False') and godot_show_article_comments %}
 <div id="godot-giscus">
+    {%- if (theme_prev_next_buttons_location == 'bottom' or theme_prev_next_buttons_location == 'both') and (next or prev) %}
+      <div class="rst-footer-buttons" role="navigation">
+        {%- if prev %}
+          <a href="{{ prev.link|e }}" class="btn btn-neutral float-left" title="{{ prev.title|striptags|e }}" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> {{ _('Previous') }}</a>
+        {%- endif %}
+        {%- if next %}
+          <a href="{{ next.link|e }}" class="btn btn-neutral float-right" title="{{ next.title|striptags|e }}" accesskey="n" rel="next">{{ _('Next') }} <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
+        {%- endif %}
+      </div>
+    {%- endif %}
     <hr>
         <h2>User-contributed notes</h2>
     <p>

about/complying_with_licenses.rst

@@ -84,39 +84,39 @@ how the text has to be included, but here are the most common approaches (you
 only need to implement one of them, not all).
 
 Credits screen
-^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~
 
 Include the above license text somewhere in the credits screen. It can be at the
 bottom after showing the rest of the credits. Most large studios use this
 approach with open source licenses.
 
 Licenses screen
-^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~
 
 Some games have a special menu (often in the settings) to display licenses.
 This menu is typically accessed with a button called **Third-party Licenses**
 or **Open Source Licenses**.
 
 Output log
-^^^^^^^^^^
+~~~~~~~~~~
 
 Printing the license text using the :ref:`print() <class_@GlobalScope_method_print>`
 function may be enough on platforms where a global output log is readable.
 This is the case on desktop platforms, Android and HTML5 (but not iOS).
 
 Accompanying file
-^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~
 
 If the game is distributed on desktop platforms, a file containing the license
 text can be added to the software that is installed to the user PC.
 
 Printed manual
-^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~
 
 If the game includes a printed manual, the license text can be included there.
 
 Link to the license
-^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~
 
 The Godot Engine developers consider that a link to ``godotengine.org/license``
 in your game documentation or credits would be an acceptable way to satisfy