From 153f45e49800830163d0ddec011f2cc5be2ec347 Mon Sep 17 00:00:00 2001
From: Jochen Hoenle <jochen.hoenle@bmw.de>
Date: Fri, 11 Sep 2026 11:33:11 +0200
Subject: [PATCH] [docs build] add examples to docs build

- use (dirty) shell script to generate docs and copy over. Is required
  to avoid cyclic dependency in bazel: tooling <-> examples
---
 .github/workflows/deploy_docs.yml             | 14 ++++
 bazel/rules/rules_score/docs/index.rst        | 10 +++
 .../examples/build_example_docs.sh            | 70 +++++++++++++++++++
 3 files changed, 94 insertions(+)
 create mode 100755 bazel/rules/rules_score/examples/build_example_docs.sh

diff --git a/.github/workflows/deploy_docs.yml b/.github/workflows/deploy_docs.yml
index b0ae2017..703bbaae 100644
--- a/.github/workflows/deploy_docs.yml
+++ b/.github/workflows/deploy_docs.yml
@@ -20,6 +20,7 @@ on:
     branches: [main]
     paths:
       - 'bazel/rules/rules_score/docs/**'
+      - 'bazel/rules/rules_score/examples/**'
       - 'coverage/**'
       - '.github/workflows/deploy_docs.yml'
   workflow_dispatch:
@@ -39,6 +40,10 @@ jobs:
         uses: actions/checkout@v7.0.1
         with:
           fetch-depth: 0 # full history needed for tag-based version detection
+      - name: Free Disk Space (Ubuntu)
+        uses: eclipse-score/more-disk-space@v1
+        with:
+          level: 4
       - name: Setup Bazel with cache
         uses: bazel-contrib/setup-bazel@0.19.0
         with:
@@ -65,6 +70,8 @@ jobs:
           fi
       - name: Build Sphinx documentation
         run: bazel build //bazel/rules/rules_score:rules_score_doc
+      - name: Build example dependable element documentation
+        run: bazel/rules/rules_score/examples/build_example_docs.sh example-docs
       - name: Generate combined coverage report
         id: coverage
         run: |
@@ -88,6 +95,13 @@ jobs:
           cp -r "${HTML_DIR}/." docs_output/
           chmod -R u+w docs_output/
 
+          # Embed the standalone example sites at docs_output/examples/<example>/
+          # (linked from docs/examples.rst)
+          if [[ -d example-docs ]]; then
+            mkdir -p docs_output/examples
+            cp -r example-docs/. docs_output/examples/
+          fi
+
           # Embed the combined coverage report at docs_output/coverage/
           if [[ -d coverage-html ]]; then
             mkdir -p docs_output/coverage
diff --git a/bazel/rules/rules_score/docs/index.rst b/bazel/rules/rules_score/docs/index.rst
index 2b05a94b..e34565a3 100644
--- a/bazel/rules/rules_score/docs/index.rst
+++ b/bazel/rules/rules_score/docs/index.rst
@@ -27,6 +27,16 @@ Rules SCORE for Bazel
    user_guide/index
    rule_reference
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Examples
+   :hidden:
+
+   Minimal <https://eclipse-score.github.io/tooling/latest/examples/minimal/index.html>
+   Other Library <https://eclipse-score.github.io/tooling/latest/examples/some_other_library/index.html>
+   SEooC <https://eclipse-score.github.io/tooling/latest/examples/seooc/index.html>
+   Integrator <https://eclipse-score.github.io/tooling/latest/examples/integrator/index.html>
+
 .. toctree::
    :maxdepth: 2
    :caption: Validation
diff --git a/bazel/rules/rules_score/examples/build_example_docs.sh b/bazel/rules/rules_score/examples/build_example_docs.sh
new file mode 100755
index 00000000..cc3bf715
--- /dev/null
+++ b/bazel/rules/rules_score/examples/build_example_docs.sh
@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# *******************************************************************************
+# 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
+# *******************************************************************************
+#
+# Builds the dependable_element documentation of every example and stages the
+# resulting HTML under <out-dir>/<example>/.
+#
+# Every example is a standalone Bazel module that reaches back into this repo
+# via local_path_override. The root module therefore cannot depend on them --
+# that would close a bazel_dep cycle -- so their docs are built out-of-band
+# here and copied into the published docs tree next to the Sphinx output of
+# //bazel/rules/rules_score:rules_score_doc.
+#
+# Usage:
+#   bazel/rules/rules_score/examples/build_example_docs.sh <out-dir>
+set -euo pipefail
+
+# "<example dir>:<dependable_element doc target>"
+EXAMPLES=(
+  "minimal:my_element_doc"
+  "some_other_library:other_seooc_doc"
+  "seooc:safety_software_seooc_example_doc"
+  "integrator:integrator_seooc_doc"
+)
+
+if [[ $# -ne 1 ]]; then
+  echo "usage: $(basename "$0") <out-dir>" >&2
+  exit 2
+fi
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+out_dir="$(mkdir -p "$1" && cd "$1" && pwd)"
+
+for entry in "${EXAMPLES[@]}"; do
+  example="${entry%%:*}"
+  target="${entry#*:}"
+
+  echo "==> Building documentation for example '${example}'"
+  (
+    cd "${script_dir}/${example}"
+    bazel build "//:${target}"
+
+    html_dir="$(bazel info bazel-bin)/${target}/html"
+    if [[ ! -d "${html_dir}" ]]; then
+      echo "error: expected HTML output not found at ${html_dir}" >&2
+      exit 1
+    fi
+
+    rm -rf "${out_dir:?}/${example}"
+    mkdir -p "${out_dir}/${example}"
+    cp -r "${html_dir}/." "${out_dir}/${example}/"
+    chmod -R u+w "${out_dir}/${example}"
+
+    # Each example runs its own Bazel server; keeping five alive at once
+    # exhausts memory on standard CI runners.
+    bazel shutdown
+  )
+done
+
+echo "==> Example documentation staged in ${out_dir}"