Skip to content

Commit 2b5f1cd

Browse files
emjay0921emjay0921
committed
feat: add multi-version documentation support
- Add new workflow for building v2.0 (root) and v1.3 (/v1.3/) - Fix version_switcher.js regex to handle /v1.3/ paths - Update switcher.json with correct version URLs This enables deploying both documentation versions: - v2.0 (latest) from v2-odoo19-doc-refresh branch at / - v1.3 from stable branch at /v1.3/
1 parent 45cfe3c commit 2b5f1cd

File tree

3 files changed

+167
-6
lines changed

3 files changed

+167
-6
lines changed

‎.github/workflows/build_deploy_multiversion.yml‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
name: Build and deploy multi-version OpenSPP documentation
2+
3+
# This workflow builds and deploys multi-version documentation:
4+
# - v2.0 (latest) from v2-odoo19-doc-refresh branch → root (/)
5+
# - v1.3 from stable branch → /v1.3/
6+
7+
on:
8+
push:
9+
branches:
10+
- stable # Only run on stable branch
11+
workflow_dispatch: # Allow manual trigger
12+
13+
jobs:
14+
build_multiversion:
15+
runs-on: ubuntu-latest
16+
steps:
17+
- name: Checkout stable branch
18+
uses: actions/checkout@v3
19+
with:
20+
ref: stable
21+
fetch-depth: 0 # Fetch all history for branch switching
22+
submodules: true
23+
24+
- name: Setup Graphviz
25+
uses: ts-graphviz/setup-graphviz@v1
26+
27+
- name: Set up Python 3.10
28+
uses: actions/setup-python@v4
29+
with:
30+
python-version: '3.10'
31+
32+
- name: Install system dependencies
33+
run: |
34+
sudo apt-get update
35+
sudo apt-get install -y libsasl2-dev libldap2-dev libssl-dev
36+
37+
# ============================================
38+
# BUILD v1.3 (from stable branch)
39+
# ============================================
40+
- name: Install v1.3 dependencies (stable)
41+
run: |
42+
pip install -q -r requirements_frozen.txt
43+
44+
- name: Build v1.3 documentation
45+
run: |
46+
set -e
47+
rm -rf _build/
48+
export DOCS_VERSION=1.3
49+
export DOCS_BASEURL=https://docs.openspp.org/v1.3/
50+
sphinx-build -b html docs _build/html/v1.3
51+
echo "✅ v1.3 build complete"
52+
53+
# ============================================
54+
# BUILD v2.0 (from v2-odoo19-doc-refresh branch)
55+
# ============================================
56+
- name: Checkout v2 docs
57+
run: |
58+
# Save v1.3 build
59+
mv _build/html/v1.3 /tmp/v1.3-build
60+
61+
# Checkout v2 branch
62+
git checkout v2-odoo19-doc-refresh
63+
git submodule update --init --recursive
64+
65+
- name: Install v2.0 dependencies
66+
run: |
67+
# Install any additional requirements for v2
68+
pip install -q -r requirements_frozen.txt || pip install -q -r requirements.txt
69+
70+
- name: Build v2.0 documentation (root)
71+
run: |
72+
set -e
73+
rm -rf _build/
74+
export DOCS_VERSION=2.0
75+
export DOCS_BASEURL=https://docs.openspp.org/
76+
sphinx-build -b html docs _build/html
77+
echo "✅ v2.0 build complete"
78+
79+
# ============================================
80+
# COMBINE BUILDS & SETUP VERSION SWITCHER
81+
# ============================================
82+
- name: Combine builds
83+
run: |
84+
# Move v1.3 build back
85+
mv /tmp/v1.3-build _build/html/v1.3
86+
echo "✅ Combined v2.0 (root) and v1.3 (/v1.3/)"
87+
88+
- name: Setup version switcher
89+
run: |
90+
set -e
91+
92+
# Create production switcher.json
93+
cat > _build/html/_static/switcher.json << 'EOF'
94+
[
95+
{
96+
"name": "2.0 (latest)",
97+
"version": "2.0",
98+
"url": "https://docs.openspp.org/"
99+
},
100+
{
101+
"name": "1.3",
102+
"version": "1.3",
103+
"url": "https://docs.openspp.org/v1.3/"
104+
}
105+
]
106+
EOF
107+
108+
# Copy to v1.3
109+
cp _build/html/_static/switcher.json _build/html/v1.3/_static/
110+
111+
# Copy version_switcher.js to both (if not already present)
112+
if [ -f "docs/_static/version_switcher.js" ]; then
113+
cp docs/_static/version_switcher.js _build/html/_static/
114+
cp docs/_static/version_switcher.js _build/html/v1.3/_static/
115+
fi
116+
117+
echo "✅ Version switcher configured"
118+
119+
- name: Inject version switcher script
120+
run: |
121+
# Inject script tag into all HTML files that don't already have it
122+
find _build/html -name "*.html" -exec grep -L "version_switcher.js" {} \; | \
123+
xargs -I {} sed -i 's|</body>|<script src="/_static/version_switcher.js"></script></body>|g' {}
124+
125+
echo "✅ Version switcher script injected"
126+
127+
- name: Display build summary
128+
run: |
129+
echo "============================================"
130+
echo "Multi-version documentation build complete"
131+
echo "============================================"
132+
echo ""
133+
echo "v2.0 (root):"
134+
ls -la _build/html/ | head -10
135+
echo ""
136+
echo "v1.3 (/v1.3/):"
137+
ls -la _build/html/v1.3/ | head -10
138+
echo ""
139+
echo "Version switcher:"
140+
cat _build/html/_static/switcher.json
141+
142+
# ============================================
143+
# DEPLOY TO CF-PAGES
144+
# ============================================
145+
- name: Deploy to cf-pages branch
146+
uses: peaceiris/actions-gh-pages@v3
147+
with:
148+
github_token: ${{ secrets.GITHUB_TOKEN }}
149+
publish_dir: _build/html
150+
publish_branch: cf-pages
151+
keep_files: true # Preserve preview deployments
152+
153+
- name: Display deployment status
154+
run: |
155+
echo "============================================"
156+
echo "✅ Multi-version documentation deployed!"
157+
echo "============================================"
158+
echo ""
159+
echo "URLs:"
160+
echo " - v2.0 (latest): https://docs.openspp.org/"
161+
echo " - v1.3: https://docs.openspp.org/v1.3/"

‎docs/_static/switcher.json‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
[
22
{
3-
"name": "stable (latest)",
4-
"version": "stable",
3+
"name": "2.0 (latest)",
4+
"version": "2.0",
55
"url": "https://docs.openspp.org/"
66
},
77
{
88
"name": "1.3",
99
"version": "1.3",
10-
"url": "https://docs.openspp.org/1.3/"
10+
"url": "https://docs.openspp.org/v1.3/"
1111
}
1212
]

‎docs/_static/version_switcher.js‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,11 +28,11 @@ document.addEventListener('DOMContentLoaded', function() {
2828
// Get current page path, removing any version prefix
2929
let currentPath = window.location.pathname;
3030

31-
// Remove version prefixes: /previews/branch-name/ or /version/
31+
// Remove version prefixes: /previews/branch-name/ or /v1.3/ or /1.3/
3232
// This regex matches /previews/anything/ at the start
3333
currentPath = currentPath.replace(/^\/previews\/[^\/]+\//, '/');
34-
// This regex matches /version-number/ patterns at the start
35-
currentPath = currentPath.replace(/^\/[0-9.]+\//, '/');
34+
// This regex matches /v1.3/ or /1.3/ patterns at the start (with optional 'v' prefix)
35+
currentPath = currentPath.replace(/^\/v?[0-9.]+\//, '/');
3636
// Remove leading slash since newUrl already has trailing slash
3737
currentPath = currentPath.replace(/^\/+/, '');
3838

0 commit comments

Comments
 (0)