From 2b5f1cda815f9581dea29214b2cc15a0af3dcb68 Mon Sep 17 00:00:00 2001 From: emjay0921 Date: Wed, 4 Feb 2026 17:54:01 +0800 Subject: [PATCH 1/4] 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/ --- .../workflows/build_deploy_multiversion.yml | 161 ++++++++++++++++++ docs/_static/switcher.json | 6 +- docs/_static/version_switcher.js | 6 +- 3 files changed, 167 insertions(+), 6 deletions(-) create mode 100644 .github/workflows/build_deploy_multiversion.yml diff --git a/.github/workflows/build_deploy_multiversion.yml b/.github/workflows/build_deploy_multiversion.yml new file mode 100644 index 000000000..339bb475b --- /dev/null +++ b/.github/workflows/build_deploy_multiversion.yml @@ -0,0 +1,161 @@ +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: 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 to both (if not already present) + if [ -f "docs/_static/version_switcher.js" ]; then + cp docs/_static/version_switcher.js _build/html/_static/ + cp docs/_static/version_switcher.js _build/html/v1.3/_static/ + fi + + 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|||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/" diff --git a/docs/_static/switcher.json b/docs/_static/switcher.json index b8034b746..51eb62acf 100644 --- a/docs/_static/switcher.json +++ b/docs/_static/switcher.json @@ -1,12 +1,12 @@ [ { - "name": "stable (latest)", - "version": "stable", + "name": "2.0 (latest)", + "version": "2.0", "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/" } ] diff --git a/docs/_static/version_switcher.js b/docs/_static/version_switcher.js index 31ac4e68c..a69c22e7d 100644 --- a/docs/_static/version_switcher.js +++ b/docs/_static/version_switcher.js @@ -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.]+\//, '/'); // Remove leading slash since newUrl already has trailing slash currentPath = currentPath.replace(/^\/+/, ''); From 58689db9a7f1b3274602b8f1b0f6ef35f467f441 Mon Sep 17 00:00:00 2001 From: emjay0921 Date: Wed, 4 Feb 2026 18:08:58 +0800 Subject: [PATCH 2/4] fix: address CI workflow issues for multi-version deployment - Disable csvlexer import in stable build (not in requirements) - Save version_switcher.js from stable before switching branches - Update old workflow to skip stable (now handled by multiversion) - Remove stable-specific code from old workflow (previews only) --- .github/workflows/build_deploy.yml | 41 ++++--------------- .../workflows/build_deploy_multiversion.yml | 18 +++++--- 2 files changed, 22 insertions(+), 37 deletions(-) diff --git a/.github/workflows/build_deploy.yml b/.github/workflows/build_deploy.yml index cadad1cff..27be6c47d 100644 --- a/.github/workflows/build_deploy.yml +++ b/.github/workflows/build_deploy.yml @@ -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: @@ -32,7 +36,6 @@ 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 @@ -40,19 +43,8 @@ jobs: 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 }} @@ -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 }} @@ -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}/" diff --git a/.github/workflows/build_deploy_multiversion.yml b/.github/workflows/build_deploy_multiversion.yml index 339bb475b..b47ebaec4 100644 --- a/.github/workflows/build_deploy_multiversion.yml +++ b/.github/workflows/build_deploy_multiversion.yml @@ -41,6 +41,15 @@ jobs: 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 @@ -108,11 +117,10 @@ jobs: # Copy to v1.3 cp _build/html/_static/switcher.json _build/html/v1.3/_static/ - # Copy version_switcher.js to both (if not already present) - if [ -f "docs/_static/version_switcher.js" ]; then - cp docs/_static/version_switcher.js _build/html/_static/ - cp docs/_static/version_switcher.js _build/html/v1.3/_static/ - fi + # 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" From 5deca221f17738e53650c12ab48f85d50997c74e Mon Sep 17 00:00:00 2001 From: emjay0921 Date: Wed, 4 Feb 2026 19:49:43 +0800 Subject: [PATCH 3/4] fix: use GitHub-owned actions instead of blocked third-party actions - Remove ts-graphviz/setup-graphviz@v1, install graphviz via apt-get - Replace peaceiris/actions-gh-pages@v3 with git commands - Preserves preview deployments when deploying to cf-pages branch --- .../workflows/build_deploy_multiversion.yml | 49 ++++++++++++++----- 1 file changed, 38 insertions(+), 11 deletions(-) diff --git a/.github/workflows/build_deploy_multiversion.yml b/.github/workflows/build_deploy_multiversion.yml index b47ebaec4..0fecd7bdb 100644 --- a/.github/workflows/build_deploy_multiversion.yml +++ b/.github/workflows/build_deploy_multiversion.yml @@ -21,9 +21,6 @@ jobs: 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: @@ -32,7 +29,7 @@ jobs: - name: Install system dependencies run: | sudo apt-get update - sudo apt-get install -y libsasl2-dev libldap2-dev libssl-dev + sudo apt-get install -y graphviz libsasl2-dev libldap2-dev libssl-dev # ============================================ # BUILD v1.3 (from stable branch) @@ -151,17 +148,47 @@ jobs: # 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 + run: | + set -e + + # Configure git + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + + # Create a temporary directory for the deployment + DEPLOY_DIR=$(mktemp -d) + cp -r _build/html/* "$DEPLOY_DIR/" + + # Fetch cf-pages branch + git fetch origin cf-pages:cf-pages || git checkout --orphan cf-pages + git checkout cf-pages + + # Preserve preview deployments (keep_files equivalent) + if [ -d "previews" ]; then + cp -r previews "$DEPLOY_DIR/" + fi + + # Clean current content except .git + find . -maxdepth 1 ! -name '.git' ! -name '.' -exec rm -rf {} + + + # Copy new content + cp -r "$DEPLOY_DIR"/* . + + # Add .nojekyll to prevent Jekyll processing + touch .nojekyll + + # Commit and push + git add -A + git commit -m "Deploy multi-version documentation (v2.0 + v1.3)" || echo "No changes to commit" + git push origin cf-pages + + # Clean up + rm -rf "$DEPLOY_DIR" - name: Display deployment status run: | echo "============================================" - echo "✅ Multi-version documentation deployed!" + echo "Multi-version documentation deployed!" echo "============================================" echo "" echo "URLs:" From afde0a3ca6930be693d323a96c20d614b5d6d68f Mon Sep 17 00:00:00 2001 From: emjay0921 Date: Wed, 4 Feb 2026 20:02:32 +0800 Subject: [PATCH 4/4] fix: swap versions - stable (v1.3) at root, doc refresh (v2.0) at /v2.0/ - v1.3 (stable) now deployed to root / - v2.0 (preview) now deployed to /v2.0/ - Updated switcher.json with correct URLs --- .../workflows/build_deploy_multiversion.yml | 64 +++++++++---------- docs/_static/switcher.json | 10 +-- 2 files changed, 37 insertions(+), 37 deletions(-) diff --git a/.github/workflows/build_deploy_multiversion.yml b/.github/workflows/build_deploy_multiversion.yml index 0fecd7bdb..4e99004c3 100644 --- a/.github/workflows/build_deploy_multiversion.yml +++ b/.github/workflows/build_deploy_multiversion.yml @@ -1,8 +1,8 @@ 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/ +# - v1.3 (stable) from stable branch -> root (/) +# - v2.0 from v2-odoo19-doc-refresh branch -> /v2.0/ on: push: @@ -32,7 +32,7 @@ jobs: sudo apt-get install -y graphviz libsasl2-dev libldap2-dev libssl-dev # ============================================ - # BUILD v1.3 (from stable branch) + # BUILD v1.3 (from stable branch) -> ROOT # ============================================ - name: Install v1.3 dependencies (stable) run: | @@ -47,22 +47,22 @@ jobs: # Save version_switcher.js for later (before switching branches) cp docs/_static/version_switcher.js /tmp/version_switcher.js - - name: Build v1.3 documentation + - name: Build v1.3 documentation (root) 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" + export DOCS_BASEURL=https://docs.openspp.org/ + sphinx-build -b html docs _build/html + echo "v1.3 build complete" # ============================================ - # BUILD v2.0 (from v2-odoo19-doc-refresh branch) + # BUILD v2.0 (from v2-odoo19-doc-refresh branch) -> /v2.0/ # ============================================ - name: Checkout v2 docs run: | # Save v1.3 build - mv _build/html/v1.3 /tmp/v1.3-build + mv _build/html /tmp/v1.3-build # Checkout v2 branch git checkout v2-odoo19-doc-refresh @@ -73,23 +73,23 @@ jobs: # 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) + - name: Build v2.0 documentation (/v2.0/) 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" + export DOCS_BASEURL=https://docs.openspp.org/v2.0/ + sphinx-build -b html docs _build/html/v2.0 + 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/)" + # Move v1.3 build back as root + mv /tmp/v1.3-build/* _build/html/ + echo "Combined v1.3 (root) and v2.0 (/v2.0/)" - name: Setup version switcher run: | @@ -99,27 +99,27 @@ jobs: cat > _build/html/_static/switcher.json << 'EOF' [ { - "name": "2.0 (latest)", - "version": "2.0", + "name": "1.3 (stable)", + "version": "1.3", "url": "https://docs.openspp.org/" }, { - "name": "1.3", - "version": "1.3", - "url": "https://docs.openspp.org/v1.3/" + "name": "2.0 (preview)", + "version": "2.0", + "url": "https://docs.openspp.org/v2.0/" } ] EOF - # Copy to v1.3 - cp _build/html/_static/switcher.json _build/html/v1.3/_static/ + # Copy to v2.0 + cp _build/html/_static/switcher.json _build/html/v2.0/_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/ + cp /tmp/version_switcher.js _build/html/v2.0/_static/ - echo "✅ Version switcher configured" + echo "Version switcher configured" - name: Inject version switcher script run: | @@ -127,7 +127,7 @@ jobs: find _build/html -name "*.html" -exec grep -L "version_switcher.js" {} \; | \ xargs -I {} sed -i 's|||g' {} - echo "✅ Version switcher script injected" + echo "Version switcher script injected" - name: Display build summary run: | @@ -135,11 +135,11 @@ jobs: echo "Multi-version documentation build complete" echo "============================================" echo "" - echo "v2.0 (root):" + echo "v1.3 (root):" ls -la _build/html/ | head -10 echo "" - echo "v1.3 (/v1.3/):" - ls -la _build/html/v1.3/ | head -10 + echo "v2.0 (/v2.0/):" + ls -la _build/html/v2.0/ | head -10 echo "" echo "Version switcher:" cat _build/html/_static/switcher.json @@ -179,7 +179,7 @@ jobs: # Commit and push git add -A - git commit -m "Deploy multi-version documentation (v2.0 + v1.3)" || echo "No changes to commit" + git commit -m "Deploy multi-version documentation (v1.3 + v2.0)" || echo "No changes to commit" git push origin cf-pages # Clean up @@ -192,5 +192,5 @@ jobs: echo "============================================" echo "" echo "URLs:" - echo " - v2.0 (latest): https://docs.openspp.org/" - echo " - v1.3: https://docs.openspp.org/v1.3/" + echo " - v1.3 (stable): https://docs.openspp.org/" + echo " - v2.0 (preview): https://docs.openspp.org/v2.0/" diff --git a/docs/_static/switcher.json b/docs/_static/switcher.json index 51eb62acf..caaf7ac19 100644 --- a/docs/_static/switcher.json +++ b/docs/_static/switcher.json @@ -1,12 +1,12 @@ [ { - "name": "2.0 (latest)", - "version": "2.0", + "name": "1.3 (stable)", + "version": "1.3", "url": "https://docs.openspp.org/" }, { - "name": "1.3", - "version": "1.3", - "url": "https://docs.openspp.org/v1.3/" + "name": "2.0 (preview)", + "version": "2.0", + "url": "https://docs.openspp.org/v2.0/" } ]