diff --git a/MODULE.bazel b/MODULE.bazel index 4352721ea..5f3648af3 100644 --- a/MODULE.bazel +++ b/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,7 @@ git_repository( commit = "781f1eecfa2fc9970fb08447588a0b4d19a7908d", remote = "https://github.com/github/codeql-coding-standards.git", ) + +register_toolchains( + "//bazel/toolchains:sphinx_toolchain", +) diff --git a/bazel/toolchains/BUILD b/bazel/toolchains/BUILD new file mode 100644 index 000000000..13025a967 --- /dev/null +++ b/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 = [ + "//third_party/breathe", + "//third_party/myst_parser", + "//third_party/pydata_sphinx_theme", + "//third_party/sphinx", + "//third_party/sphinx:sphinx-design", + "//third_party/sphinx:sphinx-needs", + "//third_party/sphinx:sphinxcontrib-plantuml", + "//third_party/sphinx_rtd_theme", + "@score_tooling//bazel/rules/rules_score:sphinx_module_ext", + ], +) + +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__"], +) diff --git a/bazel/toolchains/template/conf.template.py b/bazel/toolchains/template/conf.template.py new file mode 100644 index 000000000..cb4c0be34 --- /dev/null +++ b/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) diff --git a/docs/sphinx/BUILD b/docs/sphinx/BUILD index 2d4417506..c20fdcb28 100644 --- a/docs/sphinx/BUILD +++ b/docs/sphinx/BUILD @@ -14,6 +14,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( + "@score_tooling//bazel/rules/rules_score:rules_score.bzl", + "sphinx_module", +) load("//docs/sphinx/utils:defs.bzl", "generate_api_rst") # Create the sphinx-build binary with required dependencies @@ -93,3 +97,17 @@ 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"], +) diff --git a/requirements_lock.txt b/requirements_lock.txt index 29e55decd..3c280dfc0 100644 --- a/requirements_lock.txt +++ b/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 diff --git a/third_party/sphinx/BUILD b/third_party/sphinx/BUILD index 150c9e4f0..4c834b802 100644 --- a/third_party/sphinx/BUILD +++ b/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__"], ) diff --git a/third_party/traceability/requirements.txt b/third_party/traceability/requirements.txt index 74b530050..8c22f84fb 100644 --- a/third_party/traceability/requirements.txt +++ b/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