diff --git a/bazel/rules/rules_score/README.md b/bazel/rules/rules_score/README.md index 5546d0c2..a4fc0092 100644 --- a/bazel/rules/rules_score/README.md +++ b/bazel/rules/rules_score/README.md @@ -29,6 +29,7 @@ for safety related automotive software. | `unit` | `UnitInfo`, `CertifiedScope` | | `component` | `ComponentInfo` | | `fmea` | `AnalysisInfo` | +| `glossary` | `SphinxSourcesInfo` | | `dependability_analysis` | `DependabilityAnalysisInfo` | | `dependable_element` | HTML documentation zip (Sphinx) | @@ -152,6 +153,57 @@ by the wrapping `dependability_analysis` test. --- +## `glossary` + +```starlark +glossary( + name = "project_glossary", + srcs = ["docs/glossary.rst"], +) +``` + +**`bazel build`** — collects glossary `.rst` sources and publishes them +through `SphinxSourcesInfo` so `dependable_element` can include terminology +sections in generated HTML documentation. + +Example glossary source (`.rst`): + +```rst +Glossary +======== + +.. glossary:: + + integrity level + ASIL rating (QM, A, B, C, D) indicating required safety rigor. + + component + Software unit with defined interfaces, implementation, and tests. +``` + +Example term usage in requirements (`.trlc`): + +```trlc +ScoreReq.FeatReq FEAT_001 { + description = "The :term:`component` shall satisfy all :term:`feature requirements` assigned to integrity level B." + safety = ScoreReq.Asil.B + derived_from = [MyPkg.ASR_001@1] + version = 1 +} +``` + +Typical usage is to pass glossary targets into `dependable_element`: + +```starlark +dependable_element( + name = "my_seooc", + # ... + glossary = [":project_glossary"], +) +``` + +--- + ## `dependability_analysis` ```starlark @@ -187,6 +239,7 @@ dependable_element( architectural_design = [":my_design"], dependability_analysis = [":my_da"], components = [":my_component"], + glossary = [":project_glossary"], assumptions_of_use = [], tests = [], ) diff --git a/bazel/rules/rules_score/docs/rule_reference.rst b/bazel/rules/rules_score/docs/rule_reference.rst index ceca4bf1..9bc8dc81 100644 --- a/bazel/rules/rules_score/docs/rule_reference.rst +++ b/bazel/rules/rules_score/docs/rule_reference.rst @@ -254,6 +254,59 @@ Conditions that the *integrating project* must fulfil when using this SEooC. **Generated targets:** ```` (documentation), ``_test`` (TRLC validation) +.. _rule-glossary: + +glossary +~~~~~~~~ + +Collects glossary pages for Sphinx and forwards them to downstream +documentation assembly (for example through ``dependable_element``). + +.. code-block:: python + + glossary( + name = "project_glossary", + srcs = ["docs/glossary.rst"], + ) + +Example glossary source (``.rst``): + +.. code-block:: rst + + Glossary + ======== + + .. glossary:: + + integrity level + ASIL rating (QM, A, B, C, D) indicating required safety rigor. + + component + Software unit with defined interfaces, implementation, and tests. + +.. list-table:: + :header-rows: 1 + :widths: 18 12 10 60 + + * - Attribute + - Type + - Required + - Description + * - ``name`` + - string + - yes + - Target name + * - ``srcs`` + - label list + - yes + - ``.rst`` files containing glossary definitions + * - ``visibility`` + - — + - no + - Bazel visibility + +**Generated targets:** ```` (documentation; no standalone test) + .. _rule-arch-design: .. _rule-architectural-design: diff --git a/bazel/rules/rules_score/examples/seooc/BUILD b/bazel/rules/rules_score/examples/seooc/BUILD index e0ef69cb..3115cac7 100644 --- a/bazel/rules/rules_score/examples/seooc/BUILD +++ b/bazel/rules/rules_score/examples/seooc/BUILD @@ -55,6 +55,7 @@ dependable_element( dependability_analysis = [ ":sample_dependability_analysis", ], + glossary = ["//bazel/rules/rules_score/examples/seooc/docs:glossary"], integrity_level = "B", requirements = [ "//bazel/rules/rules_score/examples/seooc/docs/requirements:feature_requirements", diff --git a/bazel/rules/rules_score/examples/seooc/design/arch_design.rst b/bazel/rules/rules_score/examples/seooc/design/arch_design.rst index fe43befd..087f1d2a 100644 --- a/bazel/rules/rules_score/examples/seooc/design/arch_design.rst +++ b/bazel/rules/rules_score/examples/seooc/design/arch_design.rst @@ -17,6 +17,10 @@ Architectural Design This is the architectural design of the Safety Software SEooC Example: +The :term:`Architectural Design` describes how each :term:`Component` +contributes to fulfilling :term:`Feature Requirements` under the selected +:term:`Integrity Level`. + Static Architecture ------------------- diff --git a/bazel/rules/rules_score/examples/seooc/docs/BUILD b/bazel/rules/rules_score/examples/seooc/docs/BUILD index e2d391f4..442a643b 100644 --- a/bazel/rules/rules_score/examples/seooc/docs/BUILD +++ b/bazel/rules/rules_score/examples/seooc/docs/BUILD @@ -11,6 +11,7 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* load("@trlc//:trlc.bzl", "trlc_requirements", "trlc_requirements_test") +load("//bazel/rules/rules_score:rules_score.bzl", "glossary") trlc_requirements( name = "aous", @@ -30,3 +31,9 @@ trlc_requirements_test( ], visibility = ["//visibility:public"], ) + +glossary( + name = "glossary", + srcs = ["glossary.rst"], + visibility = ["//visibility:public"], +) diff --git a/bazel/rules/rules_score/examples/seooc/docs/glossary.rst b/bazel/rules/rules_score/examples/seooc/docs/glossary.rst new file mode 100644 index 00000000..fbe9f734 --- /dev/null +++ b/bazel/rules/rules_score/examples/seooc/docs/glossary.rst @@ -0,0 +1,33 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Glossary +======== + +.. glossary:: + + integrity level + ASIL rating (QM, A, B, C, D) indicating the level of safety rigor and + confidence required. D is the highest, QM is for non-safety components. + + feature requirements + High-level functional requirements describing what the safety element must do. + + architectural design + The structural design description of the SEooC, including components, + interfaces, and their interactions needed to realize the requirements. + + component + A software unit with defined responsibilities and interfaces, allocated + requirements, and associated implementation and verification evidence. diff --git a/bazel/rules/rules_score/examples/seooc/docs/requirements/assumed_system_requirements.trlc b/bazel/rules/rules_score/examples/seooc/docs/requirements/assumed_system_requirements.trlc index f6bf9ef0..08ca9c9a 100644 --- a/bazel/rules/rules_score/examples/seooc/docs/requirements/assumed_system_requirements.trlc +++ b/bazel/rules/rules_score/examples/seooc/docs/requirements/assumed_system_requirements.trlc @@ -20,7 +20,7 @@ import ScoreReq /////////////////////////////// ScoreReq.AssumedSystemReq ASR_SAMPLE_001 { - description = "The system shall provide safe and reliable numeric value management through encapsulated classes" + description = "The system shall provide safe and reliable numeric value management through encapsulated classes, compliant with the selected :term:`integrity level`." safety = ScoreReq.Asil.B version = 1 rationale = "System-level requirement for managing numeric values in a safety-critical context" diff --git a/bazel/rules/rules_score/examples/seooc/docs/requirements/feature_requirements.trlc b/bazel/rules/rules_score/examples/seooc/docs/requirements/feature_requirements.trlc index 1123a0cf..e0489002 100644 --- a/bazel/rules/rules_score/examples/seooc/docs/requirements/feature_requirements.trlc +++ b/bazel/rules/rules_score/examples/seooc/docs/requirements/feature_requirements.trlc @@ -20,7 +20,7 @@ import ScoreReq /////////////////////////////// ScoreReq.FeatReq FEAT_001 { - description = "The component shall provide a numeric value management interface that returns a `uint8_t` value on every read access" + description = "The :term:`component` shall provide a numeric value management interface that returns a `uint8_t` value on every read access, aligned with the :term:`feature requirements`." safety = ScoreReq.Asil.B derived_from = [SampleSEooC.ASR_SAMPLE_001@1] version = 1 diff --git a/bazel/rules/rules_score/private/dependable_element.bzl b/bazel/rules/rules_score/private/dependable_element.bzl index 8d391749..de9ae96f 100644 --- a/bazel/rules/rules_score/private/dependable_element.bzl +++ b/bazel/rules/rules_score/private/dependable_element.bzl @@ -724,6 +724,7 @@ def _dependable_element_index_impl(ctx): "architectural_design", "dependability_analysis", "checklists", + "glossary", ] artifacts_by_type = {} @@ -839,6 +840,7 @@ def _dependable_element_index_impl(ctx): "{architectural_design}": "\n ".join(artifacts_by_type["architectural_design"]), "{dependability_analysis}": "\n ".join(artifacts_by_type["dependability_analysis"]), "{checklists}": "\n ".join(artifacts_by_type["checklists"]), + "{glossary}": "\n ".join(artifacts_by_type["glossary"]), "{submodules}": deps_links, "{traceability_report}": traceability_report, }, @@ -1119,6 +1121,10 @@ _dependable_element_index = rule( default = [], doc = "Safety checklists targets or files.", ), + "glossary": attr.label_list( + default = [], + doc = "Glossary targets or files defining terminology and definitions.", + ), "template": attr.label( allow_single_file = [".rst"], mandatory = True, @@ -1271,6 +1277,7 @@ def dependable_element( tests, integrity_level, checklists = [], + glossary = [], deps = [], maturity = "release", sphinx = Label("//bazel/rules/rules_score:score_build"), @@ -1306,6 +1313,8 @@ def dependable_element( depend on elements with a lower integrity level than its own. checklists: Optional list of labels to .rst or .md files containing safety checklists and verification documents. + glossary: Optional list of labels to .rst files containing + terminology and definitions for the dependable element. deps: Optional list of other module targets this element depends on. Cross-references will work automatically. sphinx: Label to sphinx build binary. Default: //bazel/rules/rules_score:score_build @@ -1334,6 +1343,7 @@ def dependable_element( architectural_design = architectural_design, dependability_analysis = dependability_analysis, checklists = checklists, + glossary = glossary, tests = tests, deps = deps, processed_deps = processed_deps, diff --git a/bazel/rules/rules_score/private/glossary.bzl b/bazel/rules/rules_score/private/glossary.bzl new file mode 100644 index 00000000..fce1a480 --- /dev/null +++ b/bazel/rules/rules_score/private/glossary.bzl @@ -0,0 +1,84 @@ +# ******************************************************************************* +# 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 +# ******************************************************************************* + +""" +Glossary build rule for S-CORE projects. + +This rule accepts glossary sources as ``.rst`` files and publishes them +through ``SphinxSourcesInfo`` for the ``dependable_element`` documentation +assembly pipeline. +""" + +load("//bazel/rules/rules_score:providers.bzl", "SphinxSourcesInfo") + +# ============================================================================ +# Private Rule Implementation +# ============================================================================ + +def _glossary_impl(ctx): + """Implementation for ``glossary`` rule. + + Args: + ctx: Rule context. + + Returns: + List of providers including: + - ``DefaultInfo`` with glossary source files + - ``SphinxSourcesInfo`` where ``srcs == deps`` (leaf rule) + """ + + source_files = depset(ctx.files.srcs) + + return [ + DefaultInfo(files = source_files), + SphinxSourcesInfo( + srcs = source_files, + deps = source_files, + aux_srcs = depset(), + ), + ] + +# ============================================================================ +# Rule Definition +# ============================================================================ + +_glossary = rule( + implementation = _glossary_impl, + doc = "Collect glossary documentation files and expose them to Sphinx.", + attrs = { + "srcs": attr.label_list( + allow_files = [".rst"], + mandatory = True, + doc = "Glossary source files (``.rst``).", + ), + }, +) + +# ============================================================================ +# Public Macro +# ============================================================================ + +def glossary(name, srcs, **kwargs): + """Define a glossary artifact for documentation assembly. + + Args: + name: Target name. + srcs: List of glossary source files (.rst). + visibility: Bazel visibility specification. + """ + + _glossary( + name = name, + srcs = srcs, + **kwargs + ) diff --git a/bazel/rules/rules_score/rules_score.bzl b/bazel/rules/rules_score/rules_score.bzl index 3df157f7..9a6cb8e8 100644 --- a/bazel/rules/rules_score/rules_score.bzl +++ b/bazel/rules/rules_score/rules_score.bzl @@ -57,6 +57,10 @@ load( "//bazel/rules/rules_score/private:fmea.bzl", _fmea = "fmea", ) +load( + "//bazel/rules/rules_score/private:glossary.bzl", + _glossary = "glossary", +) load( "//bazel/rules/rules_score/private:sphinx_module.bzl", _sphinx_module = "sphinx_module", @@ -76,6 +80,7 @@ assumed_system_requirements = _assumed_system_requirements component_requirements = _component_requirements dependability_analysis = _dependability_analysis feature_requirements = _feature_requirements +glossary = _glossary filter_execpath = _filter_execpath fmea = _fmea sphinx_module = _sphinx_module diff --git a/bazel/rules/rules_score/templates/dependable_element_index.template.rst b/bazel/rules/rules_score/templates/dependable_element_index.template.rst index c6f55054..f58ae14f 100644 --- a/bazel/rules/rules_score/templates/dependable_element_index.template.rst +++ b/bazel/rules/rules_score/templates/dependable_element_index.template.rst @@ -78,6 +78,12 @@ Checklists {checklists} +.. toctree:: + :maxdepth: 2 + :caption: Glossary + + {glossary} + Submodules ---------- This module includes the following submodules: