Skip to content

feat: add multi-version documentation support #113

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
emjay0921 merged 2 commits into from
Feb 4, 2026
Merged

feat: add multi-version documentation support #113

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2b5f1cd
feat: add multi-version documentation support
emjay0921 Feb 4, 2026
58689db
fix: address CI workflow issues for multi-version deployment
emjay0921 Feb 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 9 additions & 32 deletions .github/workflows/build_deploy.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,13 @@
name: Build and deploy OpenSPP documentation
name: Build and deploy OpenSPP documentation (previews only)

# NOTE: stable branch is now handled by build_deploy_multiversion.yml
# This workflow only handles preview deployments for other branches

on:
push:
branches-ignore:
- cf-pages
- stable # stable is handled by multiversion workflow

jobs:
build_deploy:
Expand Down Expand Up @@ -32,27 +36,15 @@ jobs:

# Set safe branch name for preview deployments
- name: Set safe branch name
if: github.ref != 'refs/heads/stable'
id: branch
run: |
# Sanitize branch name: only allow alphanumeric, dots, underscores, hyphens
# Replace all other characters with hyphens and limit to 50 characters
SAFE_NAME=$(echo ${GITHUB_REF_NAME} | sed 's/[^a-zA-Z0-9._-]/-/g' | cut -c1-50)
echo "safe=${SAFE_NAME}" >> $GITHUB_OUTPUT

# Build documentation with appropriate environment variables
- name: Prepare deploy (stable)
if: github.ref == 'refs/heads/stable'
run: |
set -e # Exit on error
export DOCS_VERSION=stable
export DOCS_BASEURL=https://docs.openspp.org/
export IS_PREVIEW=0
export DOCS_GITHUB_VERSION=stable
make deploy || { echo "Build failed"; exit 1; }

# Build preview documentation
- name: Prepare deploy (preview)
if: github.ref != 'refs/heads/stable'
run: |
set -e # Exit on error
export DOCS_VERSION=${{ steps.branch.outputs.safe }}
Expand All @@ -61,19 +53,8 @@ jobs:
export DOCS_GITHUB_VERSION=${GITHUB_REF_NAME}
make deploy || { echo "Build failed"; exit 1; }

# Deploy stable documentation (main branch)
- name: Deploy stable documentation (to cf-pages branch)
if: github.ref == 'refs/heads/stable'
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: _build/html
publish_branch: cf-pages
keep_files: true # Don't delete preview versions

# Deploy preview documentation (non-main branches)
# Deploy preview documentation
- name: Deploy preview documentation (to cf-pages branch)
if: github.ref != 'refs/heads/stable'
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
Expand All @@ -84,9 +65,5 @@ jobs:

- name: Display deployment status
run: |
if [ "${{ github.ref }}" == "refs/heads/stable" ]; then
echo "✅ Deployed stable documentation to https://docs.openspp.org/"
else
BRANCH_SAFE=$(echo ${GITHUB_REF_NAME} | sed 's/\//-/g')
echo "✅ Deployed preview documentation to https://docs.openspp.org/previews/${BRANCH_SAFE}/"
fi
BRANCH_SAFE=$(echo ${GITHUB_REF_NAME} | sed 's/\//-/g')
echo "✅ Deployed preview documentation to https://docs.openspp.org/previews/${BRANCH_SAFE}/"
169 changes: 169 additions & 0 deletions .github/workflows/build_deploy_multiversion.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,169 @@
name: Build and deploy multi-version OpenSPP documentation

# This workflow builds and deploys multi-version documentation:
# - v2.0 (latest) from v2-odoo19-doc-refresh branch → root (/)
# - v1.3 from stable branch → /v1.3/

on:
push:
branches:
- stable # Only run on stable branch
workflow_dispatch: # Allow manual trigger

jobs:
build_multiversion:
runs-on: ubuntu-latest
steps:
- name: Checkout stable branch
uses: actions/checkout@v3
with:
ref: stable
fetch-depth: 0 # Fetch all history for branch switching
submodules: true

- name: Setup Graphviz
uses: ts-graphviz/setup-graphviz@v1

- name: Set up Python 3.10
uses: actions/setup-python@v4
with:
python-version: '3.10'

- name: Install system dependencies
run: |
sudo apt-get update
sudo apt-get install -y libsasl2-dev libldap2-dev libssl-dev

# ============================================
# BUILD v1.3 (from stable branch)
# ============================================
- name: Install v1.3 dependencies (stable)
run: |
pip install -q -r requirements_frozen.txt

- name: Prepare v1.3 build
run: |
# Temporarily disable csvlexer import (not in requirements_frozen.txt)
sed -i 's/from csvlexer.csv import CsvLexer/# from csvlexer.csv import CsvLexer # disabled for CI/' docs/conf.py
sed -i "s/lexers\['csv'\] = CsvLexer/# lexers['csv'] = CsvLexer # disabled for CI/" docs/conf.py

# Save version_switcher.js for later (before switching branches)
cp docs/_static/version_switcher.js /tmp/version_switcher.js

- name: Build v1.3 documentation
run: |
set -e
rm -rf _build/
export DOCS_VERSION=1.3
export DOCS_BASEURL=https://docs.openspp.org/v1.3/
sphinx-build -b html docs _build/html/v1.3
echo "✅ v1.3 build complete"

# ============================================
# BUILD v2.0 (from v2-odoo19-doc-refresh branch)
# ============================================
- name: Checkout v2 docs
run: |
# Save v1.3 build
mv _build/html/v1.3 /tmp/v1.3-build

# Checkout v2 branch
git checkout v2-odoo19-doc-refresh
git submodule update --init --recursive

- name: Install v2.0 dependencies
run: |
# Install any additional requirements for v2
pip install -q -r requirements_frozen.txt || pip install -q -r requirements.txt

- name: Build v2.0 documentation (root)
run: |
set -e
rm -rf _build/
export DOCS_VERSION=2.0
export DOCS_BASEURL=https://docs.openspp.org/
sphinx-build -b html docs _build/html
echo "✅ v2.0 build complete"

# ============================================
# COMBINE BUILDS & SETUP VERSION SWITCHER
# ============================================
- name: Combine builds
run: |
# Move v1.3 build back
mv /tmp/v1.3-build _build/html/v1.3
echo "✅ Combined v2.0 (root) and v1.3 (/v1.3/)"

- name: Setup version switcher
run: |
set -e

# Create production switcher.json
cat > _build/html/_static/switcher.json << 'EOF'
[
{
"name": "2.0 (latest)",
"version": "2.0",
"url": "https://docs.openspp.org/"
},
{
"name": "1.3",
"version": "1.3",
"url": "https://docs.openspp.org/v1.3/"
}
]
EOF

# Copy to v1.3
cp _build/html/_static/switcher.json _build/html/v1.3/_static/

# Copy version_switcher.js from stable (saved earlier) to both builds
# This ensures we use the fixed version with proper regex
cp /tmp/version_switcher.js _build/html/_static/
cp /tmp/version_switcher.js _build/html/v1.3/_static/

echo "✅ Version switcher configured"

- name: Inject version switcher script
run: |
# Inject script tag into all HTML files that don't already have it
find _build/html -name "*.html" -exec grep -L "version_switcher.js" {} \; | \
xargs -I {} sed -i 's|</body>|<script src="/_static/version_switcher.js"></script></body>|g' {}

echo "✅ Version switcher script injected"

- name: Display build summary
run: |
echo "============================================"
echo "Multi-version documentation build complete"
echo "============================================"
echo ""
echo "v2.0 (root):"
ls -la _build/html/ | head -10
echo ""
echo "v1.3 (/v1.3/):"
ls -la _build/html/v1.3/ | head -10
echo ""
echo "Version switcher:"
cat _build/html/_static/switcher.json

# ============================================
# DEPLOY TO CF-PAGES
# ============================================
- name: Deploy to cf-pages branch
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: _build/html
publish_branch: cf-pages
keep_files: true # Preserve preview deployments

- name: Display deployment status
run: |
echo "============================================"
echo "✅ Multi-version documentation deployed!"
echo "============================================"
echo ""
echo "URLs:"
echo " - v2.0 (latest): https://docs.openspp.org/"
echo " - v1.3: https://docs.openspp.org/v1.3/"
6 changes: 3 additions & 3 deletions docs/_static/switcher.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
[
{
"name": "stable (latest)",
"version": "stable",
"name": "2.0 (latest)",
"version": "2.0",
Copy link

@cursor cursor bot Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Version detection returns wrong default breaking dropdown selection

Medium Severity

The switcher.json version value changed from "stable" to "2.0", but the getCurrentVersion() function in version_switcher.js still returns 'stable' as its default fallback. Since the version comparison on line 12 checks v.version === getCurrentVersion(), the dropdown will never show the correct version as selected when the title parsing fails, because 'stable' won't match "2.0" or "1.3".

Fix in Cursor Fix in Web

"url": "https://docs.openspp.org/"
},
{
"name": "1.3",
"version": "1.3",
"url": "https://docs.openspp.org/1.3/"
"url": "https://docs.openspp.org/v1.3/"
}
]
6 changes: 3 additions & 3 deletions docs/_static/version_switcher.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,11 +28,11 @@ document.addEventListener('DOMContentLoaded', function() {
// Get current page path, removing any version prefix
let currentPath = window.location.pathname;

// Remove version prefixes: /previews/branch-name/ or /version/
// Remove version prefixes: /previews/branch-name/ or /v1.3/ or /1.3/
// This regex matches /previews/anything/ at the start
currentPath = currentPath.replace(/^\/previews\/[^\/]+\//, '/');
// This regex matches /version-number/ patterns at the start
currentPath = currentPath.replace(/^\/[0-9.]+\//, '/');
// This regex matches /v1.3/ or /1.3/ patterns at the start (with optional 'v' prefix)
currentPath = currentPath.replace(/^\/v?[0-9.]+\//, '/');
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The regex [0-9.]+ is a bit too broad and could match invalid version strings like 1..3 or .3. This could lead to unexpected behavior with malformed URLs. Consider making the pattern more specific to only match valid version number formats. For example, a pattern like \d+(\.\d+)* would be more robust, as it ensures the pattern is composed of digits separated by single dots.

// Remove leading slash since newUrl already has trailing slash
currentPath = currentPath.replace(/^\/+/, '');

Expand Down