Feat/versioned docs with flyout

.github/actions/10_docs/build_sphinx_package/action.yml

@@ -0,0 +1,92 @@
+# *******************************************************************************
+# Copyright (c) 2026 Contributors to the Eclipse Foundation
+#
+# See the NOTICE file(s) distributed with this work for additional
+# information regarding copyright ownership.
+#
+# This program and the accompanying materials are made available under the
+# terms of the Apache License Version 2.0 which is available at
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# SPDX-License-Identifier: Apache-2.0
+# *******************************************************************************
+
+name: "Build and Package Sphinx Docs"
+description: Builds //docs/sphinx:sphinx_doc with LOBSTER_SOURCE_ROOT define, injects version-flyout assets, and optionally archives output.
+inputs:
+  docs-version:
+    description: Documentation version value (e.g. "latest", "v1.2.3", "preview/my-branch").
+    required: true
+  docs-base-url:
+    description: Base GitHub Pages URL without trailing slash (e.g. "https://eclipse-score.github.io/config_management").
+    required: true
+  lobster-source-root:
+    description: URL prefix for LOBSTER traceability source links (e.g. "https://github.com/eclipse-score/config_management/blob/main/").
+    required: true
+  repository-name:
+    description: Repository name used for shared version-flyout asset paths.
+    required: true
+  output-dir:
+    description: Directory where prepared HTML output is written.
+    required: false
+    default: docs_output
+  archive-name:
+    description: Optional tar.gz output file name. If empty, archive is skipped.
+    required: false
+    default: ""
+  inject-version-flyout:
+    description: Whether to inject version flyout CSS/JS tags into HTML files.
+    required: false
+    default: "true"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Build Sphinx documentation
+      shell: bash
+      run: |
+        bazel build //docs/sphinx:sphinx_doc \
+          --define=LOBSTER_SOURCE_ROOT="${{ inputs.lobster-source-root }}"
+
+    - name: Prepare documentation output
+      shell: bash
+      run: |
+        OUTPUT_DIR="${{ inputs.output-dir }}"
+        mkdir -p "${OUTPUT_DIR}"
+        cp -r bazel-bin/docs/sphinx/sphinx_doc/html/* "${OUTPUT_DIR}"/ || \
+          cp -r bazel-out/k8-fastbuild/bin/docs/sphinx/sphinx_doc/html/* "${OUTPUT_DIR}"/ || true
+        chmod -R u+w "${OUTPUT_DIR}/"
+        touch "${OUTPUT_DIR}/.nojekyll"
+
+    - name: Inject version flyout assets into HTML
+      if: ${{ inputs.inject-version-flyout == 'true' }}
+      shell: bash
+      run: |
+        OUTPUT_DIR="${{ inputs.output-dir }}"
+        REPO_NAME="${{ inputs.repository-name }}"
+        CSS_TAG="<link rel=\"stylesheet\" type=\"text/css\" href=\"/${REPO_NAME}/_shared/css/version_flyout.css\" />"
+        JS_TAG="<script src=\"/${REPO_NAME}/_shared/js/version_flyout.js\"></script>"
+        find "${OUTPUT_DIR}" -name '*.html' -exec sed -i \
+          "s|</head>|${CSS_TAG}\n</head>|" {} +
+        find "${OUTPUT_DIR}" -name '*.html' -exec sed -i \
+          "s|</body>|${JS_TAG}\n</body>|" {} +
+
+    - name: Verify build output
+      shell: bash
+      run: |
+        OUTPUT_DIR="${{ inputs.output-dir }}"
+        if [ ! -f "${OUTPUT_DIR}/index.html" ]; then
+          echo "::error::Documentation build failed - no index.html found"
+          exit 1
+        fi
+        echo "Documentation built successfully"
+        echo "Files generated:"
+        find "${OUTPUT_DIR}" -type f | head -20 || true
+
+    - name: Archive documentation output
+      if: ${{ inputs.archive-name != '' }}
+      shell: bash
+      run: |
+        ARCHIVE_PATH="${{ inputs.archive-name }}"
+        mkdir -p "$(dirname "${ARCHIVE_PATH}")"
+        tar czf "${ARCHIVE_PATH}" -C "${{ inputs.output-dir }}" .

.github/workflows/docs.yml

@@ -30,14 +30,101 @@ on:
 
 jobs:
   build-docs:
-    uses: eclipse-score/cicd-workflows/.github/workflows/docs.yml@main
-    permissions:
-      contents: write
-      pages: write
-      pull-requests: write
-      id-token: write
-
-    with:
-      # the bazel-target depends on your repo specific docs_targets configuration (e.g. "suffix")
-      bazel-target: "//:docs -- --github_user=${{ github.repository_owner }} --github_repo=${{ github.event.repository.name }}"
-      retention-days: 3
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Bazel
+        uses: bazel-contrib/setup-bazel@0.9.1
+        with:
+          bazelisk-cache: true
+          disk-cache: ${{ github.workflow }}
+          repository-cache: true
+
+      - name: Determine version
+        id: version
+        run: |
+          if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then
+            VERSION="${GITHUB_REF#refs/tags/}"
+            echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+            echo "is_tag=true" >> "$GITHUB_OUTPUT"
+          elif [[ "${GITHUB_REF}" == refs/heads/main ]]; then
+            echo "version=latest" >> "$GITHUB_OUTPUT"
+            echo "is_tag=false" >> "$GITHUB_OUTPUT"
+          else
+            # PR — use pr-<number> for pull_request_target
+            if [[ "${{ github.event_name }}" == "pull_request_target" ]]; then
+              echo "version=pr-${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT"
+            else
+              BRANCH_NAME="${GITHUB_REF#refs/heads/}"
+              BRANCH_NAME="${BRANCH_NAME//\//-}"
+              echo "version=preview/${BRANCH_NAME}" >> "$GITHUB_OUTPUT"
+            fi
+            echo "is_tag=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build and package Sphinx documentation
+        uses: ./.github/actions/10_docs/build_sphinx_package
+        with:
+          docs-version: ${{ steps.version.outputs.version }}
+          docs-base-url: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}
+          lobster-source-root: https://github.com/${{ github.repository }}/blob/main/
+          repository-name: ${{ github.event.repository.name }}
+          output-dir: docs_output
+          archive-name: docs-${{ steps.version.outputs.version }}.tar.gz
+
+      - name: Download previously released versions
+        if: github.event_name != 'pull_request_target'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          mkdir -p publish
+          for tag in $(gh api "repos/${{ github.repository }}/releases" --paginate --jq '.[].tag_name' | grep '^v'); do
+            if gh release download "${tag}" --pattern "docs-${tag}.tar.gz" --dir /tmp 2>/dev/null; then
+              mkdir -p "publish/${tag}"
+              tar xzf "/tmp/docs-${tag}.tar.gz" -C "publish/${tag}"
+              rm -f "/tmp/docs-${tag}.tar.gz"
+              echo "Restored ${tag} from release artifact"
+            else
+              echo "::warning::No docs artifact found for release ${tag}"
+            fi
+          done
+
+      - name: Assemble publish tree
+        if: github.event_name != 'pull_request_target'
+        run: |
+          bazel run //docs/sphinx/utils:assemble_publish_tree -- \
+            --version     "${{ steps.version.outputs.version }}" \
+            --is-tag      "${{ steps.version.outputs.is_tag }}" \
+            --docs-output docs_output \
+            --publish-dir publish \
+            --repo-url    "https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}" \
+            --root-index  docs/sphinx/_gh_pages/index.html
+
+      - name: Upload documentation artifact (PRs)
+        if: github.event_name == 'pull_request_target'
+        uses: actions/upload-artifact@v4
+        with:
+          name: github-pages-${{ github.event.pull_request.head.sha }}
+          path: docs_output/
+          retention-days: 3
+          if-no-files-found: error
+
+      - name: Upload Pages artifact (push/merge)
+        if: github.event_name != 'pull_request_target'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: publish
+
+  deploy-pages:
+    needs: build-docs
+    if: github.event_name != 'pull_request_target'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

MODULE.bazel

@@ -116,12 +116,17 @@ git_override(
 bazel_dep(name = "score_lifecycle_health", version = "0.2.0")
 git_override(
     module_name = "score_lifecycle_health",
-    commit = "9a68e1efa144e1a582fe7439a9d8bf842b25b826",
-    remote = "https://github.com/Chahult/lifecycle.git",
+    commit = "7fb5140d39aca047a01880b4aa0a8ddd16d73f0f",
+    remote = "https://github.com/eclipse-score/lifecycle.git",
 )
 
 # s-core persistency
 bazel_dep(name = "score_persistency", version = "0.3.2")
+single_version_override(
+    module_name = "score_persistency",
+    patch_strip = 1,
+    patches = ["//bazel/patches:score_persistency_fix_string_view_to_string.patch"],
+)
 
 # TRLC dependency — commit matches score_tooling ade2a09e
 bazel_dep(name = "trlc", version = "0.0.0", dev_dependency = True)

bazel/patches/score_persistency_fix_string_view_to_string.patch

@@ -0,0 +1,11 @@
+--- a/src/cpp/src/internal/kvs_helper.cpp
++++ b/src/cpp/src/internal/kvs_helper.cpp
+@@ -240,7 +240,7 @@
+                                 result = score::MakeUnexpected(ErrorCode::InvalidValueType);
+                                 break;
+                             }
+-                            map.emplace(key.GetAsStringView().to_string(),
++                            map.emplace(std::string(key.GetAsStringView()),
+                                         std::make_shared<KvsValue>(std::move(conv.value())));
+                         }
+                         if (!error)

docs/sphinx/BUILD

@@ -13,6 +13,14 @@
 
 load("@score_tooling//bazel/rules/rules_score:rules_score.bzl", "sphinx_module")
 
+exports_files(
+    [
+        "_static/css/version_flyout.css",
+        "_static/js/version_flyout.js",
+    ],
+    visibility = ["//docs/sphinx/utils:__pkg__"],
+)
+
 sphinx_module(
     name = "sphinx_doc",
     testonly = True,

docs/sphinx/_gh_pages/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <title>Redirecting to latest documentation...</title>
+    <meta http-equiv="refresh" content="0; url=latest/">
+    <link rel="canonical" href="latest/">
+</head>
+<body>
+    <p>Redirecting to <a href="latest/">latest documentation</a>...</p>
+</body>
+</html>

docs/sphinx/_static/css/version_flyout.css

@@ -0,0 +1,125 @@
+/* RTD-style version flyout panel */
+.version-flyout {
+    position: fixed;
+    bottom: 0;
+    right: 20px;
+    z-index: 9999;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+    font-size: 14px;
+}
+
+.version-flyout__toggle {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    padding: 8px 16px;
+    background: #1f1f2e;
+    color: #fff;
+    border: none;
+    border-radius: 6px 6px 0 0;
+    cursor: pointer;
+    font-size: 14px;
+    font-weight: 500;
+}
+
+.version-flyout__toggle:hover {
+    background: #2a2a3d;
+}
+
+.version-flyout__toggle .flyout-icon {
+    font-size: 16px;
+}
+
+.version-flyout__toggle .flyout-current {
+    color: #27ae60;
+    font-weight: bold;
+}
+
+.version-flyout__toggle .flyout-arrow {
+    margin-left: auto;
+    transition: transform 0.2s;
+}
+
+.version-flyout__toggle.active .flyout-arrow {
+    transform: rotate(180deg);
+}
+
+.version-flyout__panel {
+    display: none;
+    background: #1f1f2e;
+    color: #ccc;
+    padding: 16px;
+    border-radius: 6px 6px 0 0;
+    min-width: 260px;
+    box-shadow: 0 -4px 16px rgba(0, 0, 0, 0.3);
+}
+
+.version-flyout__panel.open {
+    display: block;
+}
+
+.version-flyout__panel h4 {
+    color: #fff;
+    margin: 0 0 8px 0;
+    font-size: 13px;
+    text-transform: uppercase;
+    letter-spacing: 0.5px;
+}
+
+.version-flyout__panel .flyout-section {
+    margin-bottom: 12px;
+}
+
+.version-flyout__panel .flyout-versions {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 6px;
+}
+
+.version-flyout__panel .flyout-versions a {
+    color: #55b4d4;
+    text-decoration: none;
+    padding: 2px 8px;
+    border-radius: 3px;
+    font-size: 13px;
+}
+
+.version-flyout__panel .flyout-versions a:hover {
+    background: rgba(255, 255, 255, 0.1);
+    color: #7dd3fc;
+}
+
+.version-flyout__panel .flyout-versions a.active {
+    color: #27ae60;
+    font-weight: bold;
+}
+
+.version-flyout__panel .flyout-links {
+    border-top: 1px solid #333;
+    padding-top: 10px;
+    margin-top: 10px;
+}
+
+.version-flyout__panel .flyout-links a {
+    display: inline-block;
+    color: #55b4d4;
+    text-decoration: none;
+    margin-right: 12px;
+    font-size: 13px;
+}
+
+.version-flyout__panel .flyout-links a:hover {
+    color: #7dd3fc;
+}
+
+.version-flyout__footer {
+    font-size: 11px;
+    color: #888;
+    margin-top: 10px;
+    text-align: center;
+}
+
+.version-flyout__footer a {
+    color: #55b4d4;
+    text-decoration: none;
+}