Skip to content

Commit 092d937

Browse files
emjay0921emjay0921
authored
Merge pull request #117 from OpenSPP/feat/multiversion-docs
feat: add multi-version documentation support
2 parents 45cfe3c + 0521a19 commit 092d937

File tree

4 files changed

+216
-40
lines changed

4 files changed

+216
-40
lines changed

‎.github/workflows/build_deploy.yml‎

Lines changed: 9 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,13 @@
1-
name: Build and deploy OpenSPP documentation
1+
name: Build and deploy OpenSPP documentation (previews only)
2+
3+
# NOTE: stable branch is now handled by build_deploy_multiversion.yml
4+
# This workflow only handles preview deployments for other branches
25

36
on:
47
push:
58
branches-ignore:
69
- cf-pages
10+
- stable # stable is handled by multiversion workflow
711

812
jobs:
913
build_deploy:
@@ -32,27 +36,15 @@ jobs:
3236

3337
# Set safe branch name for preview deployments
3438
- name: Set safe branch name
35-
if: github.ref != 'refs/heads/stable'
3639
id: branch
3740
run: |
3841
# Sanitize branch name: only allow alphanumeric, dots, underscores, hyphens
3942
# Replace all other characters with hyphens and limit to 50 characters
4043
SAFE_NAME=$(echo ${GITHUB_REF_NAME} | sed 's/[^a-zA-Z0-9._-]/-/g' | cut -c1-50)
4144
echo "safe=${SAFE_NAME}" >> $GITHUB_OUTPUT
4245
43-
# Build documentation with appropriate environment variables
44-
- name: Prepare deploy (stable)
45-
if: github.ref == 'refs/heads/stable'
46-
run: |
47-
set -e # Exit on error
48-
export DOCS_VERSION=stable
49-
export DOCS_BASEURL=https://docs.openspp.org/
50-
export IS_PREVIEW=0
51-
export DOCS_GITHUB_VERSION=stable
52-
make deploy || { echo "Build failed"; exit 1; }
53-
46+
# Build preview documentation
5447
- name: Prepare deploy (preview)
55-
if: github.ref != 'refs/heads/stable'
5648
run: |
5749
set -e # Exit on error
5850
export DOCS_VERSION=${{ steps.branch.outputs.safe }}
@@ -61,19 +53,8 @@ jobs:
6153
export DOCS_GITHUB_VERSION=${GITHUB_REF_NAME}
6254
make deploy || { echo "Build failed"; exit 1; }
6355
64-
# Deploy stable documentation (main branch)
65-
- name: Deploy stable documentation (to cf-pages branch)
66-
if: github.ref == 'refs/heads/stable'
67-
uses: peaceiris/actions-gh-pages@v3
68-
with:
69-
github_token: ${{ secrets.GITHUB_TOKEN }}
70-
publish_dir: _build/html
71-
publish_branch: cf-pages
72-
keep_files: true # Don't delete preview versions
73-
74-
# Deploy preview documentation (non-main branches)
56+
# Deploy preview documentation
7557
- name: Deploy preview documentation (to cf-pages branch)
76-
if: github.ref != 'refs/heads/stable'
7758
uses: peaceiris/actions-gh-pages@v3
7859
with:
7960
github_token: ${{ secrets.GITHUB_TOKEN }}
@@ -84,9 +65,5 @@ jobs:
8465

8566
- name: Display deployment status
8667
run: |
87-
if [ "${{ github.ref }}" == "refs/heads/stable" ]; then
88-
echo "✅ Deployed stable documentation to https://docs.openspp.org/"
89-
else
90-
BRANCH_SAFE=$(echo ${GITHUB_REF_NAME} | sed 's/\//-/g')
91-
echo "✅ Deployed preview documentation to https://docs.openspp.org/previews/${BRANCH_SAFE}/"
92-
fi
68+
BRANCH_SAFE=$(echo ${GITHUB_REF_NAME} | sed 's/\//-/g')
69+
echo "✅ Deployed preview documentation to https://docs.openspp.org/previews/${BRANCH_SAFE}/"

‎.github/workflows/build_deploy_multiversion.yml‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
name: Build and deploy multi-version OpenSPP documentation
2+
3+
# This workflow builds and deploys multi-version documentation:
4+
# - v1.3 (stable) from stable branch -> root (/)
5+
# - v2.0 from v2-odoo19-doc-refresh branch -> /v2.0/
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: Set up Python 3.10
25+
uses: actions/setup-python@v4
26+
with:
27+
python-version: '3.10'
28+
29+
- name: Install system dependencies
30+
run: |
31+
sudo apt-get update
32+
sudo apt-get install -y graphviz libsasl2-dev libldap2-dev libssl-dev
33+
34+
# ============================================
35+
# BUILD v1.3 (from stable branch) -> ROOT
36+
# ============================================
37+
- name: Install v1.3 dependencies (stable)
38+
run: |
39+
pip install -q -r requirements_frozen.txt
40+
41+
- name: Prepare v1.3 build
42+
run: |
43+
# Temporarily disable csvlexer import (not in requirements_frozen.txt)
44+
sed -i 's/from csvlexer.csv import CsvLexer/# from csvlexer.csv import CsvLexer # disabled for CI/' docs/conf.py
45+
sed -i "s/lexers\['csv'\] = CsvLexer/# lexers['csv'] = CsvLexer # disabled for CI/" docs/conf.py
46+
47+
# Save version_switcher.js for later (before switching branches)
48+
cp docs/_static/version_switcher.js /tmp/version_switcher.js
49+
50+
- name: Build v1.3 documentation (root)
51+
run: |
52+
set -e
53+
rm -rf _build/
54+
export DOCS_VERSION=1.3
55+
export DOCS_BASEURL=https://docs.openspp.org/
56+
sphinx-build -b html docs _build/html
57+
echo "v1.3 build complete"
58+
59+
# ============================================
60+
# BUILD v2.0 (from v2-odoo19-doc-refresh branch) -> /v2.0/
61+
# ============================================
62+
- name: Checkout v2 docs
63+
run: |
64+
# Save v1.3 build
65+
mv _build/html /tmp/v1.3-build
66+
67+
# Discard local changes to conf.py (csvlexer was disabled for v1.3 build)
68+
git checkout docs/conf.py
69+
70+
# Checkout v2 branch
71+
git checkout v2-odoo19-doc-refresh
72+
git submodule update --init --recursive
73+
74+
- name: Install v2.0 dependencies
75+
run: |
76+
# Install any additional requirements for v2
77+
pip install -q -r requirements_frozen.txt || pip install -q -r requirements.txt
78+
79+
- name: Build v2.0 documentation (/v2.0/)
80+
run: |
81+
set -e
82+
rm -rf _build/
83+
export DOCS_VERSION=2.0
84+
export DOCS_BASEURL=https://docs.openspp.org/v2.0/
85+
sphinx-build -b html docs _build/html/v2.0
86+
echo "v2.0 build complete"
87+
88+
# ============================================
89+
# COMBINE BUILDS & SETUP VERSION SWITCHER
90+
# ============================================
91+
- name: Combine builds
92+
run: |
93+
# Move v1.3 build back as root
94+
mv /tmp/v1.3-build/* _build/html/
95+
echo "Combined v1.3 (root) and v2.0 (/v2.0/)"
96+
97+
- name: Setup version switcher
98+
run: |
99+
set -e
100+
101+
# Create production switcher.json
102+
cat > _build/html/_static/switcher.json << 'EOF'
103+
[
104+
{
105+
"name": "1.3 (stable)",
106+
"version": "1.3",
107+
"url": "https://docs.openspp.org/"
108+
},
109+
{
110+
"name": "2.0 (preview)",
111+
"version": "2.0",
112+
"url": "https://docs.openspp.org/v2.0/"
113+
}
114+
]
115+
EOF
116+
117+
# Copy to v2.0
118+
cp _build/html/_static/switcher.json _build/html/v2.0/_static/
119+
120+
# Copy version_switcher.js from stable (saved earlier) to both builds
121+
# This ensures we use the fixed version with proper regex
122+
cp /tmp/version_switcher.js _build/html/_static/
123+
cp /tmp/version_switcher.js _build/html/v2.0/_static/
124+
125+
echo "Version switcher configured"
126+
127+
- name: Inject version switcher script
128+
run: |
129+
# Inject script tag into all HTML files that don't already have it
130+
find _build/html -name "*.html" -exec grep -L "version_switcher.js" {} \; | \
131+
xargs -I {} sed -i 's|</body>|<script src="/_static/version_switcher.js"></script></body>|g' {}
132+
133+
echo "Version switcher script injected"
134+
135+
- name: Display build summary
136+
run: |
137+
echo "============================================"
138+
echo "Multi-version documentation build complete"
139+
echo "============================================"
140+
echo ""
141+
echo "v1.3 (root):"
142+
ls -la _build/html/ | head -10
143+
echo ""
144+
echo "v2.0 (/v2.0/):"
145+
ls -la _build/html/v2.0/ | head -10
146+
echo ""
147+
echo "Version switcher:"
148+
cat _build/html/_static/switcher.json
149+
150+
# ============================================
151+
# DEPLOY TO CF-PAGES
152+
# ============================================
153+
- name: Deploy to cf-pages branch
154+
run: |
155+
set -e
156+
157+
# Configure git
158+
git config user.name "github-actions[bot]"
159+
git config user.email "github-actions[bot]@users.noreply.github.com"
160+
161+
# Create a temporary directory for the deployment
162+
DEPLOY_DIR=$(mktemp -d)
163+
cp -r _build/html/* "$DEPLOY_DIR/"
164+
165+
# Fetch cf-pages branch
166+
git fetch origin cf-pages:cf-pages || git checkout --orphan cf-pages
167+
git checkout cf-pages
168+
169+
# Preserve preview deployments (keep_files equivalent)
170+
if [ -d "previews" ]; then
171+
cp -r previews "$DEPLOY_DIR/"
172+
fi
173+
174+
# Clean current content except .git
175+
find . -maxdepth 1 ! -name '.git' ! -name '.' -exec rm -rf {} +
176+
177+
# Copy new content
178+
cp -r "$DEPLOY_DIR"/* .
179+
180+
# Add .nojekyll to prevent Jekyll processing
181+
touch .nojekyll
182+
183+
# Commit and push
184+
git add -A
185+
git commit -m "Deploy multi-version documentation (v1.3 + v2.0)" || echo "No changes to commit"
186+
git push origin cf-pages
187+
188+
# Clean up
189+
rm -rf "$DEPLOY_DIR"
190+
191+
- name: Display deployment status
192+
run: |
193+
echo "============================================"
194+
echo "Multi-version documentation deployed!"
195+
echo "============================================"
196+
echo ""
197+
echo "URLs:"
198+
echo " - v1.3 (stable): https://docs.openspp.org/"
199+
echo " - v2.0 (preview): https://docs.openspp.org/v2.0/"

‎docs/_static/switcher.json‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
[
22
{
3-
"name": "stable (latest)",
4-
"version": "stable",
3+
"name": "1.3 (stable)",
4+
"version": "1.3",
55
"url": "https://docs.openspp.org/"
66
},
77
{
8-
"name": "1.3",
9-
"version": "1.3",
10-
"url": "https://docs.openspp.org/1.3/"
8+
"name": "2.0 (preview)",
9+
"version": "2.0",
10+
"url": "https://docs.openspp.org/v2.0/"
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)