Skip to content

Commit 6ba1726

Browse files
Arctis-FireblightArctis-Fireblight
authored
Merge pull request #141 from MichaelFisher1997/optimize-build-simplify
ci: Add GitHub Actions workflow for Cloudflare Pages deployment
2 parents 5518aec + eb241df commit 6ba1726

6 files changed

Lines changed: 284 additions & 123 deletions

File tree

‎.github/workflows/build-and-deploy.yml‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
name: Build and Deploy Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
- optimize-build-simplify
8+
pull_request:
9+
branches:
10+
- master
11+
12+
concurrency:
13+
group: ${{ github.workflow }}-${{ github.ref }}
14+
cancel-in-progress: true
15+
16+
jobs:
17+
build:
18+
runs-on: ubuntu-latest
19+
timeout-minutes: 120
20+
21+
steps:
22+
- name: Checkout repository
23+
uses: actions/checkout@v4
24+
25+
- name: Set up Python
26+
uses: actions/setup-python@v5
27+
with:
28+
python-version: '3.11'
29+
cache: 'pip'
30+
31+
- name: Install dependencies
32+
run: |
33+
python -m pip install --upgrade pip
34+
pip install -r requirements.txt
35+
36+
- name: Cache migrated files
37+
uses: actions/cache@v4
38+
id: cache-migrated
39+
with:
40+
path: _migrated
41+
key: migrated-${{ hashFiles('**/*.rst', 'conf.py', 'migrate.py') }}
42+
43+
- name: Cache Sphinx doctrees
44+
uses: actions/cache@v4
45+
with:
46+
path: _sphinx/.doctrees
47+
key: doctrees-${{ github.ref }}-${{ github.run_id }}
48+
restore-keys: |
49+
doctrees-${{ github.ref }}-
50+
doctrees-
51+
52+
- name: Build documentation
53+
run: |
54+
export FULL_RUN=1
55+
bash build.sh
56+
env:
57+
FULL_RUN: 1
58+
59+
- name: Upload build artifact
60+
uses: actions/upload-artifact@v4
61+
with:
62+
name: redot-docs-build
63+
path: output/
64+
retention-days: 1
65+
66+
deploy:
67+
needs: build
68+
runs-on: ubuntu-latest
69+
if: github.event_name == 'push' && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/optimize-build-simplify')
70+
71+
steps:
72+
- name: Download build artifact
73+
uses: actions/download-artifact@v4
74+
with:
75+
name: redot-docs-build
76+
path: output/
77+
78+
- name: Determine deploy directory
79+
run: |
80+
if [ "${{ github.ref_name }}" = "master" ]; then
81+
echo "DEPLOY_DIR=output/html/en/latest" >> $GITHUB_ENV
82+
else
83+
echo "DEPLOY_DIR=output/html/en/${{ github.ref_name }}" >> $GITHUB_ENV
84+
fi
85+
86+
- name: Deploy to Cloudflare Pages
87+
uses: cloudflare/wrangler-action@v3
88+
with:
89+
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
90+
accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
91+
command: pages deploy ${{ env.DEPLOY_DIR }} --project-name=redot-docs --branch=${{ github.ref_name }}

.github/workflows/ci.yml renamed to .github/workflows/ci.yml.disabled

File renamed without changes.

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,4 +54,5 @@ _build/
5454
_migrated/
5555
_sphinx/
5656
_repo/
57+
output/
5758
*.log

‎README.md‎

Lines changed: 79 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -16,20 +16,75 @@ For mobile devices or e-readers, you can also download an ePub copy (updated eve
1616
[latest](https://download.redotengine.org/docs/redot-docs-epub-master.zip). Extract
1717
the ZIP archive then open the `RedotEngine.epub` file in an e-book reader application.
1818

19-
## Migrating
19+
## Building Documentation
2020

21-
We are transitioning from Godot to Redot. In this period, a temporary solution is available.
21+
### Quick Build (Local Development)
2222

23+
For local development, use the optimized build script:
24+
25+
```bash
26+
# Full build (includes migration + Sphinx)
27+
FULL_RUN=1 ./build.sh
28+
29+
# The output will be in output/html/en/latest/ (for master branch)
30+
# or output/html/en/<branch-name>/ (for other branches)
2331
```
24-
python migrate.py . _migrated True
32+
33+
**Build optimizations:**
34+
- `--exclude-classes`: Skips class reference migration (faster, these are auto-generated)
35+
- `-j auto`: Uses all available CPU cores for parallel builds
36+
- Branch mapping: `master` → `latest/`, other branches → `<branch-name>/`
37+
38+
### Manual Build
39+
40+
If you prefer manual control:
41+
42+
```bash
43+
# 1. Migrate (optional - skip for faster builds, use --exclude-classes)
44+
python migrate.py --exclude-classes . _migrated
45+
46+
# 2. Build with Sphinx (auto-detect CPU cores)
47+
sphinx-build -b html -j auto ./_migrated/ _build/html
2548
```
2649

27-
After the docs are converted, you can build with
50+
### Architecture
51+
52+
**GitHub Actions + Cloudflare Pages (Current):**
53+
- Source: This repository (`Redot-Engine/redot-docs`)
54+
- Build: GitHub Actions runs `build.sh` (2-hour timeout vs Cloudflare's 20 minutes)
55+
- Deploy: Built output pushed to Cloudflare Pages
56+
- Output: `/output/html/en/<branch>/`
57+
- Serve: Cloudflare Pages serves the built documentation
58+
59+
**Previous architectures (deprecated):**
60+
1. ~Two repos: `redot-docs` (source) → builds → pushes to `redot-docs-live` (deployment)~
61+
2. ~Direct Cloudflare Pages build (hit 20-minute timeout limit)~
62+
63+
### GitHub Actions Workflow
64+
65+
The repository includes an automated workflow (`.github/workflows/build-and-deploy.yml`) that:
2866

67+
1. **Builds on every push** to `master` or `optimize-build-simplify`
68+
2. **Runs on GitHub Actions** with a 2-hour timeout (vs Cloudflare's 20-minute limit)
69+
3. **Deploys automatically** to Cloudflare Pages using the official Cloudflare action
70+
71+
**Setup required:**
72+
73+
Add these secrets to your GitHub repository (Settings → Secrets and variables → Actions):
74+
- `CLOUDFLARE_ACCOUNT_ID` - Your Cloudflare account ID
75+
- `CLOUDFLARE_API_TOKEN` - API token with Cloudflare Pages:Edit permission
76+
77+
**How it works:**
2978
```
30-
sphinx-build -b html ./_migrated/ _build/html
79+
Push to branch → GitHub Actions builds (30 min) → Deploys to Cloudflare Pages
3180
```
3281

82+
**Benefits:**
83+
- No 20-minute timeout limit
84+
- Python dependencies cached between builds
85+
- Automatic deployment on every push
86+
- Works for both production (master) and preview branches
87+
3388
## Theming
3489

3590
The Redot documentation uses the default `sphinx_rtd_theme` with many
@@ -58,24 +113,31 @@ Here are some quick links to the areas you might be interested in:
58113

59114
### How to build with anaconda/miniconda
60115

61-
```
62-
# 1) create env with Python 3.11
116+
**Recommended: Use the build script**
117+
```bash
118+
# Setup environment (one-time)
63119
conda create -n redot-docs python=3.11 -y
64-
65-
# 2) activate it
66120
conda activate redot-docs
121+
pip install -r requirements.txt
122+
123+
# Build documentation
124+
FULL_RUN=1 ./build.sh
67125

68-
# 3) ensure pip is available (usually is)
69-
conda install pip -y
126+
# Output: output/html/en/latest/
127+
```
70128

71-
# 4) from the repo root, install requirements via pip
72-
python -m pip install -r requirements.txt
129+
**Manual build (if you need fine control):**
130+
```bash
131+
# 1) Setup environment
132+
conda create -n redot-docs python=3.11 -y
133+
conda activate redot-docs
134+
pip install -r requirements.txt
73135

74-
# 5) Migration
75-
python migrate.py . _migrated True
136+
# 2) Migrate (use --exclude-classes for faster builds)
137+
python migrate.py --exclude-classes . _migrated
76138

77-
# 6) build the docs
78-
sphinx-build -b html ./_migrated/ _build/html
139+
# 3) Build with Sphinx (auto-detect CPU cores)
140+
sphinx-build -b html -j auto ./_migrated/ _build/html
79141
```
80142

81143
## License

0 commit comments

Comments
 (0)