Add automated documentation build workflow for 26.1 LTS#143
Merged
Arctis-Fireblight merged 24 commits intoRedot-Engine:masterfrom Feb 12, 2026
Merged
Conversation
- Add BUILD_DIR environment variable to build.sh for versioned output - Update workflow to build stable (4.3), 4.4, and dev branches - Deploy all versions to Cloudflare Pages - Add stable -> 4.4 and latest -> dev redirects - Enable deployment from feature/versioning-setup branch for testing
Add fetch-depth: 0 to actions/checkout to ensure stable and 4.4 branches are available for building versioned documentation.
Remove git fetch commands and checkout origin/stable and origin/4.4 directly since fetch-depth: 0 already brings all branches.
Add upstream remote and fetch stable/4.4 branches from Redot-Engine/redot-docs instead of relying on origin which may not have these branches in forks.
Add index.html at root level that redirects to stable (4.4) version. Cloudflare Pages needs an index.html at the deploy root.
Use GitHub Actions matrix strategy to build 4.3, 4.4, and dev versions in parallel. Each version builds independently, then artifacts are combined in deploy job. Should reduce total build time from ~72 minutes to ~25 minutes (lengthiest single build).
Change relative URLs (4.4/, dev/) to absolute paths (/4.4/, /dev/) to prevent infinite redirect loops when accessing versioned docs.
Save build.sh from current branch before checking out upstream/stable or upstream/4.4, then restore it after checkout. This ensures we use the BUILD_DIR-aware build script even when building older branches that don't have this feature.
…, dev) - Add godot_versions list to html_context in conf.py - Update versions.html template to use godot_versions instead of hardcoded stable/latest - Show actual version numbers (4.3, 4.4, 26.1, dev, stable, latest) in dropdown
Add set -x and echo statements to see exactly what's happening when checking out upstream branches and running the build. This will help identify why builds are failing on upstream/stable and upstream/4.4.
Check if migrate.py supports --exclude-classes flag before using it. Upstream branches (4.4, stable) have older migrate.py that doesn't support this flag, causing 'required arguments missing' error.
When gitBranch is HEAD (upstream checkout), we know we're on an old branch that doesn't support --exclude-classes flag. Use simple syntax for upstream branches and --exclude-classes only for our feature branch.
Remove stable, latest, and 26.1 from version list to simplify. Update root redirect to go directly to 4.4. Remove stable.html and latest.html redirects.
Stop copying conf.py from feature branch to upstream branches. Each branch needs its own version settings: - 4.4 branch should show '4.4', not 'dev' - 4.3 branch should show '4.3' - Only feature branch shows 'dev' This fixes the issue where 4.4 docs were showing dev branding and warning banner.
- Add fallback in versions.html for branches without godot_versions defined - Copy updated versions.html template to upstream branches during build - This ensures all versions show the same version selector dropdown - 4.3 and 4.4 branches will now properly show version list even without godot_versions in conf.py
- Single build job for 26.1 LTS - Deploy directly to root (no subdirectories) - Removed multi-version matrix for simplicity
- Build to 26.1 directory - Copy files to dist folder for artifact - Deploy from downloaded artifact root
Workflow was building from feature/versioning-setup branch instead of 26.1. Now explicitly fetches and checks out origin/26.1 before building.
The 26.1 branch has old build.sh without BUILD_DIR support. Now we save the updated build.sh to /tmp first, then use it after checking out 26.1 branch. This ensures BUILD_DIR works correctly.
- Checkout upstream/master (has MCP docs and latest content) - Use conf.py from origin/26.1 (shows version 26.1) - This gives us all master content labeled as 26.1 LTS
📝 WalkthroughWalkthroughThis pull request updates the build and deployment pipeline to support versioned documentation. Changes include CI/CD workflow orchestration to handle a new 26.1 branch, build script modifications to accept a BUILD_DIR override, Sphinx configuration updates to reference a new Redot engine base path and add version listings, and template changes to dynamically render version selectors. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Author
Author
|
Setup Instructions for Maintainers: Before merging this PR, please create a &26.1 branch upstream: After the 26.1 branch exists upstream, this workflow will work correctly. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
conf.py (1)
212-213:⚠️ Potential issue | 🟡 Minor
html_extra_pathis overwritten—robots.txtwill be excluded.Line 213 reassigns
html_extra_path, discarding therobots.txtfrom line 212. Both files should be included.🔧 Proposed fix
-html_extra_path = ["robots.txt"] -html_extra_path = ["sitemap.xml"] +html_extra_path = ["robots.txt", "sitemap.xml"]
🤖 Fix all issues with AI agents
In `@build.sh`:
- Around line 73-81: The condition that checks both BUILD_DIR and gitBranch
prevents using --exclude-classes in detached HEAD (gitBranch == "HEAD"), so
change the logic in the build.sh block that calls migrate.py to rely only on
BUILD_DIR: if [ -n "$BUILD_DIR" ]; then call python migrate.py --exclude-classes
"$inputDir" "$migrateDir" else call python migrate.py "$inputDir" "$migrateDir"
fi, leaving the gitBranch/git rev-parse logic alone or removing the gitBranch
check so that --exclude-classes is used whenever BUILD_DIR is set regardless of
detached HEAD state.
In `@conf.py`:
- Around line 194-204: The configuration is for the 26.1 LTS build but
godot_version is set to "dev" and godot_versions doesn't include 26.1; change
the godot_version constant to "26.1" and update the godot_versions list to
include an entry for ("26.1", "/26.1/") (and remove or reorder the "dev" entry
if the LTS build shouldn’t advertise it), ensuring the symbols godot_version and
godot_versions in conf.py reflect the 26.1 LTS values.
🧹 Nitpick comments (2)
.github/workflows/build-and-deploy.yml (2)
57-70: Cache key may not reflect the runtimeconf.pystate.The cache key at line 62 uses
hashFiles('**/*.rst', 'conf.py', 'migrate.py'), butconf.pyis overwritten at runtime (line 44) after checkout. The hash is computed from the checked-out upstream/master'sconf.py, not the 26.1 version that's actually used during the build.This could lead to:
- Cache hits when the actual config differs
- Unexpected cache misses when only the 26.1 config changes
Consider either:
- Computing the hash after overwriting
conf.py, or- Including the 26.1 branch ref in the cache key explicitly
Option: Include branch ref in cache key
- key: migrated-26.1-${{ hashFiles('**/*.rst', 'conf.py', 'migrate.py') }} + key: migrated-26.1-${{ hashFiles('**/*.rst', 'migrate.py') }}-conf-26.1
75-81: RedundantBUILD_DIRdeclaration.
BUILD_DIRis set via bothexport(line 77) and theenvblock (line 81). Theenvblock alone is sufficient and cleaner.Remove redundant export
- name: Build documentation for 26.1 run: | # Use the saved build.sh which supports BUILD_DIR - export FULL_RUN=1 - export BUILD_DIR="26.1" /tmp/build-with-versions.sh env: FULL_RUN: 1 BUILD_DIR: "26.1"
Comment on lines
+73
to
+81
| # Check if we're building from upstream branch (doesn't support --exclude-classes) | ||
| # by checking if BUILD_DIR is set (our feature branch sets it, upstream builds won't) | ||
| if [ -n "$BUILD_DIR" ] && [ "$gitBranch" != "HEAD" ]; then | ||
| # Our branch with new migrate.py - use --exclude-classes | ||
| python migrate.py --exclude-classes "$inputDir" "$migrateDir" | ||
| else | ||
| # Upstream branch - old migrate.py, don't use --exclude-classes | ||
| python migrate.py "$inputDir" "$migrateDir" | ||
| fi |
There was a problem hiding this comment.
Logic flaw: detached HEAD state defeats the --exclude-classes flag.
When the workflow runs git checkout upstream/master, Git enters detached HEAD state where git rev-parse --abbrev-ref HEAD returns "HEAD". Since the condition requires gitBranch != "HEAD", the --exclude-classes flag will never be used in the CI workflow even when BUILD_DIR is set.
If the intent is to use --exclude-classes whenever BUILD_DIR is set (regardless of HEAD state), simplify the condition:
🔧 Proposed fix
- # Check if we're building from upstream branch (doesn't support --exclude-classes)
- # by checking if BUILD_DIR is set (our feature branch sets it, upstream builds won't)
- if [ -n "$BUILD_DIR" ] && [ "$gitBranch" != "HEAD" ]; then
+ # Use --exclude-classes when BUILD_DIR is set (our versioned builds)
+ if [ -n "$BUILD_DIR" ]; then
# Our branch with new migrate.py - use --exclude-classes
python migrate.py --exclude-classes "$inputDir" "$migrateDir"
else📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| # Check if we're building from upstream branch (doesn't support --exclude-classes) | |
| # by checking if BUILD_DIR is set (our feature branch sets it, upstream builds won't) | |
| if [ -n "$BUILD_DIR" ] && [ "$gitBranch" != "HEAD" ]; then | |
| # Our branch with new migrate.py - use --exclude-classes | |
| python migrate.py --exclude-classes "$inputDir" "$migrateDir" | |
| else | |
| # Upstream branch - old migrate.py, don't use --exclude-classes | |
| python migrate.py "$inputDir" "$migrateDir" | |
| fi | |
| # Use --exclude-classes when BUILD_DIR is set (our versioned builds) | |
| if [ -n "$BUILD_DIR" ]; then | |
| # Our branch with new migrate.py - use --exclude-classes | |
| python migrate.py --exclude-classes "$inputDir" "$migrateDir" | |
| else | |
| # Upstream branch - old migrate.py, don't use --exclude-classes | |
| python migrate.py "$inputDir" "$migrateDir" | |
| fi |
🤖 Prompt for AI Agents
In `@build.sh` around lines 73 - 81, The condition that checks both BUILD_DIR and
gitBranch prevents using --exclude-classes in detached HEAD (gitBranch ==
"HEAD"), so change the logic in the build.sh block that calls migrate.py to rely
only on BUILD_DIR: if [ -n "$BUILD_DIR" ]; then call python migrate.py
--exclude-classes "$inputDir" "$migrateDir" else call python migrate.py
"$inputDir" "$migrateDir" fi, leaving the gitBranch/git rev-parse logic alone or
removing the gitBranch check so that --exclude-classes is used whenever
BUILD_DIR is set regardless of detached HEAD state.
Comment on lines
+194
to
+204
| "godot_version": "dev", | ||
| # Enables a banner that displays the up-to-date status of each article. | ||
| "godot_show_article_status": True, | ||
| # Display user-contributed notes at the bottom of pages that don't have `:allow_comments: False` at the top. | ||
| "godot_show_article_comments": on_rtd and not is_i18n, | ||
| # Available documentation versions for the version selector | ||
| "godot_versions": [ | ||
| ("4.3", "/4.3/"), | ||
| ("4.4", "/4.4/"), | ||
| ("dev", "/dev/"), | ||
| ], |
There was a problem hiding this comment.
Version configuration appears inconsistent with 26.1 LTS purpose.
This conf.py is meant for the 26.1 LTS build, but:
godot_versionis set to"dev"(line 194) instead of"26.1"godot_versionslist (lines 200-204) contains4.3,4.4,devbut not26.1
If this conf.py will be used for 26.1 LTS documentation, update the values accordingly:
🔧 Suggested fix for 26.1 LTS configuration
- "godot_version": "dev",
+ "godot_version": "26.1",
# Enables a banner that displays the up-to-date status of each article.
"godot_show_article_status": True,
# Display user-contributed notes at the bottom of pages that don't have `:allow_comments: False` at the top.
"godot_show_article_comments": on_rtd and not is_i18n,
# Available documentation versions for the version selector
"godot_versions": [
("4.3", "/4.3/"),
("4.4", "/4.4/"),
+ ("26.1", "/26.1/"),
("dev", "/dev/"),
],📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| "godot_version": "dev", | |
| # Enables a banner that displays the up-to-date status of each article. | |
| "godot_show_article_status": True, | |
| # Display user-contributed notes at the bottom of pages that don't have `:allow_comments: False` at the top. | |
| "godot_show_article_comments": on_rtd and not is_i18n, | |
| # Available documentation versions for the version selector | |
| "godot_versions": [ | |
| ("4.3", "/4.3/"), | |
| ("4.4", "/4.4/"), | |
| ("dev", "/dev/"), | |
| ], | |
| "godot_version": "26.1", | |
| # Enables a banner that displays the up-to-date status of each article. | |
| "godot_show_article_status": True, | |
| # Display user-contributed notes at the bottom of pages that don't have `:allow_comments: False` at the top. | |
| "godot_show_article_comments": on_rtd and not is_i18n, | |
| # Available documentation versions for the version selector | |
| "godot_versions": [ | |
| ("4.3", "/4.3/"), | |
| ("4.4", "/4.4/"), | |
| ("26.1", "/26.1/"), | |
| ("dev", "/dev/"), | |
| ], |
🤖 Prompt for AI Agents
In `@conf.py` around lines 194 - 204, The configuration is for the 26.1 LTS build
but godot_version is set to "dev" and godot_versions doesn't include 26.1;
change the godot_version constant to "26.1" and update the godot_versions list
to include an entry for ("26.1", "/26.1/") (and remove or reorder the "dev"
entry if the LTS build shouldn’t advertise it), ensuring the symbols
godot_version and godot_versions in conf.py reflect the 26.1 LTS values.
Author
Setup InstructionsThis PR adds automated documentation builds for Redot 26.1 LTS. Before Merging:
What This Does:
Result:Users see 26.1 LTS docs with all the latest content. |
Arctis-Fireblight
approved these changes
Feb 12, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Automated Documentation Build for Redot 26.1 LTS
This PR adds a GitHub Actions workflow to build and deploy 26.1 LTS documentation.
What It Does:
Setup Required Before Merge:
After Merge:
Documentation will automatically build and deploy on every push to master.