Mb sphinx toolchain

MODULE.bazel

@@ -36,6 +36,11 @@ git_override(
 )
 
 bazel_dep(name = "score_tooling", version = "1.1.2")
+git_override(
+    module_name = "score_tooling",
+    commit = "09189d4c46fe0ebc92c87c507ffe215005d30360",
+    remote = "https://github.com/eclipse-score/tooling.git",
+)
 
 # Dependencies required for development that will not get propagated to our users as transitive dependencies
 bazel_dep(name = "gcc_toolchain", version = "0.9.0", dev_dependency = True)
@@ -274,16 +279,12 @@ git_override(
     remote = "https://github.com/bmw-software-engineering/trlc.git",
 )
 
-lobster_ext = use_extension("//third_party/lobster:lobster.bzl", "lobster_ext")
-use_repo(lobster_ext, "lobster")
-
-# Use lobster's upstream requirements.txt directly for this module's Python hub
-pip.parse(
-    hub_name = "lobster_dependencies",
-    python_version = "3.12",
-    requirements_lock = "@lobster//:requirements.txt",
+bazel_dep(name = "lobster", version = "0.0.0")
+git_override(
+    module_name = "lobster",
+    commit = "56881461f9d3fde2918d1731aa5937aaf64cd67c",
+    remote = "https://github.com/bmw-software-engineering/lobster.git",
 )
-use_repo(pip, "lobster_dependencies")
 
 bazel_dep(name = "rules_oci", version = "1.8.0", dev_dependency = True)
 
@@ -330,3 +331,8 @@ git_repository(
     commit = "781f1eecfa2fc9970fb08447588a0b4d19a7908d",
     remote = "https://github.com/github/codeql-coding-standards.git",
 )
+
+register_toolchains(
+    "//bazel/toolchains:sphinx_toolchain",
+)
+

bazel/toolchains/BUILD

@@ -0,0 +1,47 @@
+load(
+    "@score_tooling//bazel/rules/rules_score:sphinx_toolchain.bzl",
+    "sphinx_toolchain",
+)
+
+# ============================================================================
+# Toolchain for the score build
+# ============================================================================
+py_binary(
+    name = "sphinx_build",
+    srcs = ["@score_tooling//bazel/rules/rules_score:src/sphinx_wrapper.py"],
+    data = [],
+    main = "@score_tooling//bazel/rules/rules_score:src/sphinx_wrapper.py",
+    visibility = ["//:__subpackages__"],
+    deps = [
+        "@score_tooling//bazel/rules/rules_score:sphinx_module_ext",
+        "//third_party/breathe",
+        "//third_party/myst_parser",
+        "//third_party/pydata_sphinx_theme",
+        "//third_party/sphinx",
+        "//third_party/sphinx:sphinx-needs",
+        "//third_party/sphinx:sphinx-design",
+        "//third_party/sphinx:sphinxcontrib-plantuml",
+        "//third_party/sphinx_rtd_theme",
+    ],
+)
+
+sphinx_toolchain(
+    name = "score_sphinx_toolchain",
+    conf_template = "template/conf.template.py",
+    sphinx = ":sphinx_build",
+)
+
+toolchain(
+    name = "sphinx_toolchain",
+    exec_compatible_with = [
+        "@platforms//os:linux",
+        "@platforms//cpu:x86_64",
+    ],
+    target_compatible_with = [
+        "@platforms//os:linux",
+        "@platforms//cpu:x86_64",
+    ],
+    toolchain = ":score_sphinx_toolchain",
+    toolchain_type = "@score_tooling//bazel/rules/rules_score:toolchain_type",
+    visibility = ["//:__subpackages__"],
+)

bazel/toolchains/template/conf.template.py

@@ -0,0 +1,107 @@
+# *******************************************************************************
+# Copyright (c) 2025 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
+# *******************************************************************************
+
+"""
+Generic Sphinx configuration template for SCORE modules.
+
+This file is auto-generated from a template and should not be edited directly.
+Template variables like {PROJECT_NAME} are replaced during Bazel build.
+"""
+
+import bazel_sphinx_needs
+
+# Project configuration - {PROJECT_NAME} will be replaced by the module name during build
+project = "{PROJECT_NAME}"
+author = "S-CORE"
+version = "1.0"
+release = "1.0.0"
+project_url = (
+    "https://github.com/eclipse-score"  # Required by score_metamodel extension
+)
+
+# Sphinx extensions - comprehensive list for SCORE modules
+extensions = [
+    "sphinx_needs",
+    "sphinx_design",
+    "myst_parser",
+    "sphinxcontrib.plantuml",
+]
+
+# MyST parser extensions
+myst_enable_extensions = ["colon_fence"]
+
+# Exclude patterns for Bazel builds
+exclude_patterns = [
+    "bazel-*",
+    ".venv*",
+]
+
+# Enable markdown rendering
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+# -- Options for HTML output --
+html_theme = 'pydata_sphinx_theme'
+
+# Professional theme configuration inspired by modern open-source projects
+html_theme_options = {
+    # Navigation settings
+    'navigation_depth': 4,
+    'collapse_navigation': False,
+    'show_nav_level': 2,  # Depth of sidebar navigation
+    'show_toc_level': 2,  # Depth of page table of contents
+
+    # Header layout
+    'navbar_align': 'left',
+    'navbar_start': ['navbar-logo'],
+    'navbar_center': ['navbar-nav'],
+    'navbar_end': ['navbar-icon-links', 'theme-switcher'],
+
+    # Search configuration
+    'search_bar_text': 'Search documentation...',
+
+    # Footer configuration
+    'footer_start': ['copyright'],
+    'footer_end': ['sphinx-version'],
+
+    # Navigation buttons
+    'show_prev_next': True,
+
+    # Logo configuration
+    'logo': {
+        'text': 'Eclipse S-CORE',
+    },
+
+    # External links - S-CORE GitHub
+    'icon_links': [
+        {
+            'name': 'S-CORE GitHub',
+            'url': 'https://github.com/eclipse-score',
+            'icon': 'fab fa-github',
+        }
+    ],
+}
+
+
+# Enable numref for cross-references
+numfig = True
+
+# Load external needs and log configuration
+needs_external_needs = bazel_sphinx_needs.load_external_needs()
+bazel_sphinx_needs.log_config_info(project)
+
+
+def setup(app):
+    return bazel_sphinx_needs.setup_sphinx_extension(app, needs_external_needs)

docs/sphinx/BUILD

@@ -15,6 +15,10 @@ load("@rules_python//python:defs.bzl", "py_binary")
 load("@rules_python//sphinxdocs:sphinx.bzl", "sphinx_build_binary", "sphinx_docs")
 load("@rules_python//sphinxdocs:sphinx_docs_library.bzl", "sphinx_docs_library")
 load("//docs/sphinx/utils:defs.bzl", "generate_api_rst")
+load(
+    "@score_tooling//bazel/rules/rules_score:rules_score.bzl",
+    "sphinx_module",
+)
 
 # Create the sphinx-build binary with required dependencies
 # This wrapper approach is used for older environments (e.g. Sphinx <=7.2.* and rules_python 1.2)
@@ -93,3 +97,18 @@ sphinx_docs(
         "//score/mw/com:readme_md",
     ],
 )
+
+sphinx_module(
+    name = "sphinx_doc",
+    srcs = 
+        [
+            "how_to_document.rst",
+            "index.rst",
+            "introduction.rst",
+            "message_passing.rst",
+            "//score/mw/com:readme_md",
+        ],
+    index = "index.rst",
+    visibility = ["//visibility:public"],
+
+)

requirements_lock.txt

@@ -182,6 +182,20 @@ jinja2==3.1.6 \
     # via
     #   myst-parser
     #   sphinx
+jsonschema-rs==0.37.4 \
+    --hash=sha256:03b34f911e99343fc388651688683010daee538a3cf8cf86a7997bca28fdf16b \
+    --hash=sha256:0f17a61deb557faa57dffb9596e4f022873404f935114367788b1eebdec2bb00 \
+    --hash=sha256:10fd978a145a6f8d11373879e7d0ff232b409f77c7faf608e6b4549a7f90aaed \
+    --hash=sha256:1d3f8c8b376966c19fd4183fa979dbadc9fdd6070f2bfa4d127bdf70946963cc \
+    --hash=sha256:393ece7037a0d19fd528f7a67a32749453876468871a0bd2267909a57d8d4e32 \
+    --hash=sha256:5975e448092e99d6cc60793a71f0fee516dbf0fd1e6d2f6f1e4689627268f344 \
+    --hash=sha256:67f36f1c445c70f9975d17a84ce37f79593f6234d7eb292830d7749e5fa58ff4 \
+    --hash=sha256:75f3b4e0707dcb3dccf911ff49e387b4db54957fe1a19d3423015a65e3762057 \
+    --hash=sha256:a56d154b638deb947dbd0dfc285c349eb23a877221f2b0496a2dfa25948cc239 \
+    --hash=sha256:dedf72e5e673e3af5b9925979fd71484debada61fb7a3dfabf9bbc74b8012664 \
+    --hash=sha256:e159075b1846718466998d5a9294c661113b347b8b4749767680a97c8ed2bf4d \
+    --hash=sha256:e93a8720f6e858d872dc2882e7d3b3243ee76f7aa4d60048272773d44df466e7
+    # via sphinx-needs
 markdown-it-py==4.0.0 \
     --hash=sha256:87327c59b172c5011896038353a81343b6754500a08cd7a4973bb48c6d578147 \
     --hash=sha256:cb0a2b4aa34f932c007117b194e945bd74e0ec24133ceb5bac59009cda1cb9f3
@@ -287,6 +301,20 @@ mdurl==0.1.2 \
     --hash=sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8 \
     --hash=sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba
     # via markdown-it-py
+minijinja==2.19.0 \
+    --hash=sha256:0cf0ee1abf477c91caf8730cd19ab01960c6be124af9cd1fcbd546a4bfde36bb \
+    --hash=sha256:2725643b1d19f4f60614153bee6ea1a291c6aa410071b61299113cfca1c23e20 \
+    --hash=sha256:38ed4fef67f550ae8552b261f3a40d389bab782f1dc19e8a015b3ad25da03bc1 \
+    --hash=sha256:3defd79efd5af849dd48e3ab03b67772dc30fe53935316c953f77868938da77d \
+    --hash=sha256:487d2def6d16d30ad0cb7b0e949afb06815e144e502d0cf4465cd34fa429361e \
+    --hash=sha256:695ce4264dbe6422ef45a344dc2c1044eb3a7543606e1b4a255df5b443074462 \
+    --hash=sha256:86693fff42fdf9e6c6684b5b44e79ee708b9419e6331ffe217bbcbe7c2de6016 \
+    --hash=sha256:a59e1d23b5e62aca1c527869a0ba09126fdc9c69d43beeccb3cf07c36fc8fbe5 \
+    --hash=sha256:c2bacdeca8ca5d30035e8e78d119faca248b5ba0597200937a56980880d7d11d \
+    --hash=sha256:c2e95fd56a8ab9419403ea7f25273a6b570495116bc1af21fb4c178f4d9c5ff7 \
+    --hash=sha256:cc7ef1f9dbdaa9d47c75d7f903d55cbd766c55b38ec195c0ba11e880566bbcf3 \
+    --hash=sha256:fa11ceea225e0458ff8126de18c3baad936106cefe95ac9c9b65795bd71b018f
+    # via sphinx-needs
 myst-parser==5.0.0 \
     --hash=sha256:ab31e516024918296e169139072b81592336f2fef55b8986aa31c9f04b5f7211 \
     --hash=sha256:f6f231452c56e8baa662cc352c548158f6a16fcbd6e3800fc594978002b94f3a
@@ -407,7 +435,13 @@ requests==2.32.5 \
     --hash=sha256:dbba0bac56e100853db0ea71b82b4dfd5fe2bf6d3754a8893c3af500cec7d7cf
     # via
     #   docker
+    #   requests-file
     #   sphinx
+    #   sphinx-needs
+requests-file==2.1.0 \
+    --hash=sha256:0f549a3f3b0699415ac04d167e9cb39bccfb730cb832b4d20be3d9867356e658 \
+    --hash=sha256:cf270de5a4c5874e84599fc5778303d496c10ae5e870bfa378818f35d21bda5c
+    # via sphinx-needs
 roman-numerals==4.1.0 \
     --hash=sha256:1af8b147eb1405d5839e78aeb93131690495fe9da5c91856cb33ad55a7f1e5b2 \
     --hash=sha256:647ba99caddc2cc1e55a51e4360689115551bf4476d90e8162cf8c345fe233c7
@@ -428,8 +462,24 @@ sphinx==9.1.0 \
     #   breathe
     #   myst-parser
     #   pydata-sphinx-theme
+    #   sphinx-data-viewer
+    #   sphinx-design
+    #   sphinx-needs
     #   sphinx-rtd-theme
     #   sphinxcontrib-jquery
+    #   sphinxcontrib-plantuml
+sphinx-data-viewer==0.1.5 \
+    --hash=sha256:a7d5e58613562bb745380bfe61ca8b69997998167fd6fa9aea55606c9a4b17e4 \
+    --hash=sha256:b74b1d304c505c464d07c7b225ed0d84ea02dcc88bc1c49cdad7c2275fbbdad4
+    # via sphinx-needs
+sphinx-design==0.7.0 \
+    --hash=sha256:d2a3f5b19c24b916adb52f97c5f00efab4009ca337812001109084a740ec9b7a \
+    --hash=sha256:f82bf179951d58f55dca78ab3706aeafa496b741a91b1911d371441127d64282
+    # via -r ./third_party/traceability/requirements.txt
+sphinx-needs==8.0.0 \
+    --hash=sha256:540c380c074d4088a557ea353e91513bfc1cb7712b10925c13ac9e5ebb7be091 \
+    --hash=sha256:c4336ee0e3c949eff9eb11a14910f7b6b68cb8284d731cfddf97694037337674
+    # via -r ./third_party/traceability/requirements.txt
 sphinx-rtd-theme==3.1.0 \
     --hash=sha256:1785824ae8e6632060490f67cf3a72d404a85d2d9fc26bce3619944de5682b89 \
     --hash=sha256:b44276f2c276e909239a4f6c955aa667aaafeb78597923b1c60babc76db78e4c
@@ -449,11 +499,16 @@ sphinxcontrib-htmlhelp==2.1.0 \
 sphinxcontrib-jquery==4.1 \
     --hash=sha256:1620739f04e36a2c779f1a131a2dfd49b2fd07351bf1968ced074365933abc7a \
     --hash=sha256:f936030d7d0147dd026a4f2b5a57343d233f1fc7b363f68b3d4f1cb0993878ae
-    # via sphinx-rtd-theme
+    # via
+    #   sphinx-needs
+    #   sphinx-rtd-theme
 sphinxcontrib-jsmath==1.0.1 \
     --hash=sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178 \
     --hash=sha256:a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8
     # via sphinx
+sphinxcontrib-plantuml==0.31 \
+    --hash=sha256:fd74752f8ea070e641c3f8a402fccfa1d4a4056e0967b56033d2a76282d9f956
+    # via -r ./third_party/traceability/requirements.txt
 sphinxcontrib-qthelp==2.0.0 \
     --hash=sha256:4fe7d0ac8fc171045be623aba3e2a8f613f8682731f9153bb2e40ece16b9bbab \
     --hash=sha256:b18a828cdba941ccd6ee8445dbe72ffa3ef8cbe7505d8cd1fa0d42d3f2d5f3eb
@@ -468,6 +523,7 @@ typing-extensions==4.15.0 \
     # via
     #   beautifulsoup4
     #   pydata-sphinx-theme
+    #   sphinx-needs
 urllib3==2.6.3 \
     --hash=sha256:1b62b6884944a57dbe321509ab94fd4d3b307075e0c2eae991ac71ee15ad38ed \
     --hash=sha256:bf272323e553dfb2e87d9bfd225ca7b0f467b919d7bbd355436d3fd37cb0acd4

third_party/sphinx/BUILD

@@ -16,5 +16,23 @@ load("@score_communication_pip//:requirements.bzl", "requirement")
 alias(
     name = "sphinx",
     actual = requirement("sphinx"),
-    visibility = ["//visibility:public"],
+    visibility = ["//:__subpackages__"],
+)
+
+alias(
+    name = "sphinx-needs",
+    actual = requirement("sphinx-needs"),
+    visibility = ["//:__subpackages__"],
+)
+
+alias(
+    name = "sphinx-design",
+    actual = requirement("sphinx-design"),
+    visibility = ["//:__subpackages__"],
+)
+
+alias(
+    name = "sphinxcontrib-plantuml",
+    actual = requirement("sphinxcontrib-plantuml"),
+    visibility = ["//:__subpackages__"],
 )

third_party/traceability/requirements.txt

@@ -18,6 +18,9 @@ pyparsing>=3.0.0
 
 # Sphinx documentation dependencies
 sphinx == 9.1.0
+sphinx-needs  == 8.0.0
+sphinx-design == 0.7.0
+sphinxcontrib-plantuml ==0.31 
 breathe == 4.36.0
 myst-parser == 5.0.0
 pydata-sphinx-theme == 0.16.1