diff --git a/MODULE.bazel b/MODULE.bazel index 77b1a27..50f96b6 100644 --- a/MODULE.bazel +++ b/MODULE.bazel @@ -96,3 +96,4 @@ bazel_dep(name = "score_platform", version = "0.1.1") # Grab dash bazel_dep(name = "score_dash_license_checker", version = "0.1.1") +bazel_dep(name = "score_process", version = "0.2.0") diff --git a/docs/BUILD b/docs/BUILD index 56c0f2c..a3afa87 100644 --- a/docs/BUILD +++ b/docs/BUILD @@ -31,17 +31,30 @@ docs( "json_url": "https://eclipse-score.github.io/score/main/needs.json", "id_prefix": "score_", }, + { + "base_url": "https://eclipse-score.github.io/process_description/main", + "json_url": "https://eclipse-score.github.io/process_description/main/needs.json", + "id_prefix": "process_", + }, ], }, { "suffix": "release", # The version imported from MODULE.bazel - "target": ["@score_platform//docs:docs_needs"], + "target": [ + "@score_platform//docs:docs_needs", + "@score_process//process:docs_needs_latest", + ], "external_needs_info": [ { "base_url": "https://eclipse-score.github.io/score/main", "json_path": "/score_platform~/docs/docs_needs/_build/needs/needs.json", "id_prefix": "score_", }, + { + "base_url": "https://eclipse-score.github.io/process_description/main", + "json_path": "/score_process~/process/docs_needs_latest/_build/needs/needs.json", + "id_prefix": "process_", + }, ], }, ], diff --git a/docs/conf.py b/docs/conf.py index bac0a5e..bc91991 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -40,6 +40,8 @@ "score_layout", ] +myst_enable_extensions = ["colon_fence"] + exclude_patterns = [ # The following entries are not required when building the documentation via 'bazel # build //docs:docs', as that command runs in a sandboxed environment. However, when diff --git a/docs/docs-as-code/features.md b/docs/docs-as-code/features.md new file mode 100644 index 0000000..0534608 --- /dev/null +++ b/docs/docs-as-code/features.md @@ -0,0 +1,121 @@ +(features)= +# ๐Ÿ“˜ S-CORE Docs-as-Code โ€“ Features + +Note: this is the normal "features" ;-) + +This document outlines the key features of the S-CORE docs-as-code tooling. +Core capabilities of [Sphinx](https://www.sphinx-doc.org/) and [sphinx-needs](https://sphinx-needs.readthedocs.io/) are assumed and extended with S-CORE-specific conventions and infrastructure. + +### Input Format + +- Supports both reStructuredText (reST) and Markdown (CommonMark/GFM) + +### Build + +- Ensures deterministic output: identical input produces identical output +- โœ… Uses version-controlled configuration to ensure reproducibility +- โœ… Behaves consistently across different repositories and environments (e.g., local, CI/CD) +- โœ… Supports incremental builds to provide fast feedback during authoring +- โœ… Seamless integration with the Bazel build system + +### Configuration + +- โœ… Uses a single, shared, version-controlled configuration file +- โœ… Allows repository-specific overrides when needed +- โœ… Supports easy configuration of the metamodel (e.g., used roles, types) +- โœ… Ensures consistency with process and quality requirements + + + +### Cross-Repository Linking + +- โœ… Supports unidirectional links to: + - Versioned documentation (for tagged releases) + - Latest documentation (e.g. `main` branch) +- โœ… Keeps linked repositories and their rendered websites unaffected by incoming references +- Allows bidirectional links for integration-focused documentation +- In addition to high level versioning of repositories, supports verifying suspect links on a requirement level + +### Previews & Feedback + +- โœ… Automatically generates documentation previews for pull requests +- Previews are available within minutes of each push +- โœ… Preview output matches final published artifacts (identical rendering) + +### IDE & Developer Experience + +- โœ… Live preview functionality for documentation authors +- โœ… Integrated linting for: + - Syntax and formatting (reST and Markdown) + - Internal and external link validity + - โœ… Metamodel compliance +- Auto-completion support for: + - Cross-repository links + - Sphinx directives and roles (planned) + +### Architecture Visualization + +- โœ… Generates architecture diagrams from structured models +- Integrates diagram tools such as PlantUML and Mermaid + +### Code Integration + +- โœ… Enables traceability between documentation and source code by linking from implementation to requirements + + +## โš™๏ธ Bazel Support +*Used as the core build system across S-CORE* + +- โœ… Automatically validates changes to the S-CORE Bazel registry +- โœ… IDE support for editing Bazel `BUILD` and `.bzl` files (via LSP, plugins) + + +## ๐Ÿš€ CI/CD Integration + +- builds are cached and re-used where possible + +## ๐Ÿชช Copyright Checker + +- Ensures all S-CORE repositories use whitelisted 3rd party dependencies + - โœ… Python dependencies + - โœ… Rust dependencies + +## ๐Ÿ“œ License Compliance + +- โœ… All used 3rd-party dependencies must be from a whitelisted set +- License checks: + - โœ… Python + - โœ… Rust + - Bazel + - C++ + + + +## ๐Ÿงน Linting + +- reStructuredText +- Markdown +- Python +- Bazel +- Rust +- C++ +- GitHub Actions workflows + +## ๐Ÿงฑ Formatting + +- reStructuredText +- Markdown +- โœ… Python +- โœ… Bazel +- Rust +- C++ +- GitHub Actions workflows + +## Project Helper (to be named) + +- Provide estimated work per month, by summing up the issues per month multiplied by their size +- Exports all issues of a project to a CSV file + +## Repository Overview + +- โœ… Provide an overview of all S-CORE repositories, including their status (https://github.com/eclipse-score). diff --git a/docs/docs-as-code/index.rst b/docs/docs-as-code/index.rst index 73867ed..96e1aae 100644 --- a/docs/docs-as-code/index.rst +++ b/docs/docs-as-code/index.rst @@ -15,12 +15,20 @@ ============ -Docs-as-Code +Docs-as-Code ============ -.. grid:: 1 1 2 2 +.. grid:: 1 1 3 3 :class-container: score-grid + .. grid-item-card:: + + Features/Requirements + ^^^ + Detailed list of docs-as-code capabilities. + :ref:`Features `. :ref:`Requirements `. + + .. grid-item-card:: Getting started with docs-as-code @@ -30,7 +38,7 @@ Docs-as-Code .. grid-item-card:: - Information about Extensions + Information about Extensions ^^^ Head over to our extensions to learn about what we offer and how to configure,extend or integrate them. :ref:`See our extensions here ` @@ -40,5 +48,8 @@ Docs-as-Code .. toctree:: :maxdepth: 1 :caption: Contents: + :hidden: Getting Started + Features + Requirements diff --git a/docs/docs-as-code/requirements.rst b/docs/docs-as-code/requirements.rst new file mode 100644 index 0000000..d5d2559 --- /dev/null +++ b/docs/docs-as-code/requirements.rst @@ -0,0 +1,381 @@ +.. _requirements: + +================================= +Requirements (Process Compliance) +================================= + +Overview +-------- + +.. needtable:: + :filter: c.this_doc() + :columns: id;title;implemented + :style: datatables + +Details +---------------------- + +.. note:: + To stay consistent with sphinx-needs (the tool behind docs-as-code), we'll use `need` + for any kind of model element like a requirement, an architecture element or a + feature description. + +---------------------- +๐Ÿ“› ID Rules +---------------------- + +.. tool_req:: Enforces need ID uniqueness + :id: tool_req__attr_id + :implemented: YES + :satisfies: + PROCESS_gd_req__req__attr_uid, + PROCESS_gd_req__tool__attr_uid, + + Need IDs must be globally unique. + + .. note:: + Implementation note (in some sort of DR in the future??). + IDs are unique within one docs-instance, this is guaranteed by sphinx-needs. + Several docs-instances are always independent. When they are linked, they always + receive unique prefixes for their IDs. + +.. tool_req:: Enforces need ID scheme + :id: tool_req__attr_id_scheme + :implemented: YES + :satisfies: PROCESS_gd_req__req__attr_uid + + Need IDs must: + + * Start with the need type (e.g. ``feature__``) + * Include the feature name (for feature requirements) + * Have additional text + + This applies to needs of type: + + * Stakeholder requirements + * Feature requirements + * Component requirements + +---------------------- +๐Ÿงพ Title Requirements +---------------------- + +.. tool_req:: Enforces title wording rules + :id: tool_req__attr_title + :implemented: PARTIAL + :satisfies: PROCESS_gd_req__requirements_attr_title + + + Titles must not contain the words: + * ``shall`` + * ``must`` + * ``will`` + + Applies to: + + * stakeholder requirements + * feature requirements + * component requirements + + .. warning:: + Process requirement forbids only ``shall``. + + + +--------------------------- +๐Ÿ“ Description Requirements +--------------------------- + +.. tool_req:: Enforces presence of description + :id: tool_req__attr_description + :implemented: NO + :satisfies: PROCESS_gd_req__requirements_attr_description + + Each requirement must contain a non-empty description. + + Applies to: + + * Stakeholder requirement + * Feature requirement + * Component requirement + * Assumption of use requirement + * Process requirement + + .. warning:: + All those "applies to" need to be matched exactly against available types, + e.g. "process requirement" is quite vague. + + +------------------------- +๐Ÿง  Rationale Requirements +------------------------- + +.. tool_req:: Enforces rationale attribute + :id: tool_req__attr_rationale + :implemented: YES + :satisfies: PROCESS_gd_req__req__attr_rationale + + Each stakeholder requirement must contain a non-empty ``rationale`` attribute. + +-------------------------- +๐Ÿท๏ธ Requirement Type Rules +-------------------------- + +.. tool_req:: Enforces requirement type classification + :id: tool_req__attr_type + :implemented: YES + :satisfies: PROCESS_gd_req__req__attr_type + + The ``reqtype`` attribute must be one of: + + * Functional + * Interface + * Process + * Legal + * Non-Functional + + Applies to: + + * Stakeholder requirement + * Feature requirement + * Component requirement + * Assumption of use requirement + * Process requirement + +---------------------------- +๐Ÿ” Security Classification +---------------------------- + +.. tool_req:: Enforces security classification + :id: tool_req__attr_security + :implemented: YES + :satisfies: + PROCESS_gd_req__requirements_attr_security, + PROCESS_gd_req__arch_attr_security, + + The ``security`` attribute must be one of: + + * YES + * NO + + It is mandatory for: + + * stakeholder requirements + * feature requirements + * component requirements + * assumption of use requirements + * process requirements + * Tool Verification Report + + .. warning:: + the architecture requirement does not talk about architecture elements, but about requirements. + +--------------------------- +๐Ÿ›ก๏ธ Safety Classification +--------------------------- + +.. tool_req:: Enforces safety classification + :id: tool_req__attr_safety + :implemented: YES + :satisfies: PROCESS_gd_req__req__attr_safety + + Needs of type: + + * stakeholder requirements + * feature requirements + * component requirements + * assumption of use requirements + * process requirements + * Tool Verification Report + + shall have a automotive safety integrity level (``safety``) identifier: + + * QM + * ASIL_B + * ASIL_D + + .. warning:: + the architecture requirement does not talk about architecture elements, but about requirements. + +---------------------------- +๐Ÿ“ˆ Status Classification +---------------------------- + +.. tool_req:: Enforces status classification (1st part) + :id: tool_req__attr_status + :implemented: YES + :satisfies: + PROCESS_gd_req__req__attr_status, + PROCESS_gd_req__arch__attr_status, + + Needs of type: + + * stakeholder requirements + * feature requirements + * component requirements + * assumption of use requirements + * process requirements + * Tool Verification Report + + shall have an ``status`` attribute, which must be one of: + + * valid + * invalid + + .. warning:: + the architecture requirement does not talk about architecture elements, but about requirements. + +.. tool_req:: Enforces status classification (tool Verification Report) + :id: tool_req__attr_status_tool_verification + :implemented: YES + :satisfies: PROCESS_gd_req__tool__attr_status + + The Tool Verification Report shall have an ``status`` attribute, which must be one of: + + * draft + * evaluated + * qualified + * released + * rejected + +------------------------- +"requirement covered" +------------------------- + +.. tool_req:: Enables marking requirements as "covered" + :id: tool_req__covered + :implemented: PARTIAL + :satisfies: PROCESS_gd_req__attr_req_cov + :status: invalid + + To be clarified. + + +.. tool_req:: Support requirements test coverage + :id: tool_req__req_test_cov + :implemented: NO + :satisfies: PROCESS_gd_req__req__attr_test_covered + + | Requirements shall allow for an attribute that shows if the requirement is covered by linked test cases. + | Allowed values: + + * Yes + * No + +------------------------- +๐Ÿ”— "requirement linkage" +------------------------- + +.. TODO: Check if this is actually enforced / implemented as described. +.. tool_req:: Enables linking from/to requirements + :id: tool_req__linkage + :implemented: YES + :satisfies: PROCESS_gd_req__req__linkage + + The tool shall allow and check for linking of requirements to specific levels. + In the table underneath you can see which requirement type can link to which other one + + .. table:: + :widths: auto + + ======================== =========================== + Requirement Type Allowed Link Target + ======================== =========================== + Stakeholder Feature Requirements + Feature Requirements Component Requirements + Workflows Process Requirements + ======================== =========================== + + +---------------- +๐Ÿ“Ž Code Linkage +---------------- + +.. tool_req:: Supports linking to source code + :id: tool_req__attr_impl + :implemented: PARTIAL + :satisfies: PROCESS_gd_req__req__attr_impl + + Source code can link to requirements. + + +.. tool_req:: Supports linking to test cases + :id: tool_req__test_case_linkage + :implemented: NO + :satisfies: PROCESS_gd_req__req__attr_testlink + + Docs-as-code shall provide a way to automatically link test cases to requirements + + + +-------------------------- +๐Ÿ— Requirement Level Types +-------------------------- + +.. tool_req:: Supports multiple requirement levels + :id: tool_req__requirement_levels + :implemented: YES + :satisfies: PROCESS_gd_req__req__attr_uid + + The tool supports the following requirement levels: + + * Stakeholder requirements + * Feature requirements + * Component requirements + * Assumption of use requirements + * Process requirements + + +.. needextend:: c.this_doc() and type == 'tool_req' + :safety: QM + :security: NO + :reqtype: Functional + + +.. needextend:: c.this_doc() and type == 'tool_req' and not status + :status: valid + + +-------------------------- +๐Ÿ— Metamodel +-------------------------- + +.. tool_req:: Supports requirement metamodel + :id: tool_req__metamodel + :implemented: YES + :satisfies: + PROCESS_gd_req__req__structure, + PROCESS_gd_req__requirements_attr_description, + PROCESS_gd_req__req__attr_type, + PROCESS_gd_req__requirements_attr_security, + PROCESS_gd_req__req__attr_safety, + PROCESS_gd_req__req__attr_status, + PROCESS_gd_req__req__attr_rationale, + PROCESS_gd_req__req__linkage, + PROCESS_gd_req__req__attr_mandatory, + PROCESS_gd_req__req__linkage_fulfill, + PROCESS_gd_req__req__linkage_architecture, + PROCESS_gd_req__arch__build_blocks, + PROCESS_gd_req__arch__build_blocks_corr, + PROCESS_gd_req__arch_attr_security, + PROCESS_gd_req__arch__attr_safety, + PROCESS_gd_req__arch__attr_status, + PROCESS_gd_req__arch__attr_fulfils, + PROCESS_gd_req__arch__traceability, + + The docs-as-code metamodel shall enforce process requirements. + + .. note:: only process requirements which are fully covered by metamodel.yml are linked to this catch-all requirement! + +.. tool_req:: Supports requirement metamodel (partially implemented) + :id: tool_req__metamodel_partial + :implemented: PARTIAL + :satisfies: + PROCESS_gd_req__requirements_attr_title, + PROCESS_gd_req__req__attr_desc_weak, + PROCESS_gd_req__req__attr_req_cov, + PROCESS_gd_req__req__attr_test_covered, + + The docs-as-code metamodel shall enforce process requirements. + + .. note:: once implemented, move the satisfies-links to tool_req__metamodel. This list contains not fully implemented or non understood requirements. diff --git a/src/extensions/score_metamodel/checks/attributes_format.py b/src/extensions/score_metamodel/checks/attributes_format.py index a001740..55992d8 100644 --- a/src/extensions/score_metamodel/checks/attributes_format.py +++ b/src/extensions/score_metamodel/checks/attributes_format.py @@ -11,11 +11,10 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* +from score_metamodel import CheckLogger, local_check from sphinx.application import Sphinx from sphinx_needs.data import NeedsInfoType -from score_metamodel import CheckLogger, local_check - # req-#id: gd_req__req__attr_uid @local_check @@ -46,6 +45,7 @@ def check_id_format(app: Sphinx, need: NeedsInfoType, log: CheckLogger): "workflow", "gd_chklst", "std_req", + "tool_req", "role", "doc_concept", "gd_temp", diff --git a/src/extensions/score_metamodel/checks/check_options.py b/src/extensions/score_metamodel/checks/check_options.py index 05a0504..ca675cd 100644 --- a/src/extensions/score_metamodel/checks/check_options.py +++ b/src/extensions/score_metamodel/checks/check_options.py @@ -11,10 +11,6 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* import re - -from sphinx.application import Sphinx -from sphinx_needs.config import NeedType -from sphinx_needs.data import NeedsInfoType from collections.abc import Generator from score_metamodel import ( @@ -22,6 +18,9 @@ default_options, local_check, ) +from sphinx.application import Sphinx +from sphinx_needs.config import NeedType +from sphinx_needs.data import NeedsInfoType FieldCheck = tuple[dict[str, str], bool] CheckingDictType = dict[str, list[FieldCheck]] diff --git a/src/extensions/score_metamodel/metamodel.yaml b/src/extensions/score_metamodel/metamodel.yaml index 8d7c0b8..9619eb4 100644 --- a/src/extensions/score_metamodel/metamodel.yaml +++ b/src/extensions/score_metamodel/metamodel.yaml @@ -14,13 +14,15 @@ needs_types_base_options: optional_options: - source_code_link: "^https://github.com/eclipse-score/score/blob/.*$" + source_code_link: ^https://github.com/eclipse-score/score/blob/.*$ # Custom semantic validation rules prohibited_words: + # reqId PROCESS_gd_req__requirements_attr_title title: - shall - must - will + # reqId PROCESS_gd_req__req__attr_desc_weak content: - just - about @@ -30,7 +32,6 @@ needs_types_base_options: - absolutely needs_types: - ############################################################################## # Process Metamodel ############################################################################## @@ -64,124 +65,124 @@ needs_types: # Standards std_req: - title: "Standard Requirement" - prefix: "std_req__" + title: Standard Requirement + prefix: std_req__ mandatory_options: - id: "std_req__(iso26262|isosae21434|isopas8926|aspice_40)__[0-9a-zA-Z_-]*$" - status: "^(valid)$" + id: std_req__(iso26262|isosae21434|isopas8926|aspice_40)__[0-9a-zA-Z_-]*$ + status: ^(valid)$ optional_links: - links: "^.*$" + links: ^.*$ std_wp: - title: "Standard Work Product" - prefix: "std_wp__" + title: Standard Work Product + prefix: std_wp__ mandatory_options: - id: "std_wp__(iso26262|isosae21434|isopas8926|aspice_40)__[0-9a-z_]*$" - status: "^(valid)$" + id: std_wp__(iso26262|isosae21434|isopas8926|aspice_40)__[0-9a-z_]*$ + status: ^(valid)$ # Workflow workflow: - title: "Workflow" - prefix: "wf__" + title: Workflow + prefix: wf__ mandatory_options: - id: "^wf__[0-9a-z_]*$" - status: "^(valid|draft)$" + id: ^wf__[0-9a-z_]*$ + status: ^(valid|draft)$ mandatory_links: - input: "^wp__.*$" - output: "^wp__.*$" - approved_by: "^rl__.*$" - responsible: "^rl__.*$" + input: ^wp__.*$ + output: ^wp__.*$ + approved_by: ^rl__.*$ + responsible: ^rl__.*$ optional_links: - supported_by: "^rl__.*$" - contains: "^gd_(req|temp|chklst|guidl|meth)__.*$" - has: "^doc_(getstrt|concept)__.*$" + supported_by: ^rl__.*$ + contains: ^gd_(req|temp|chklst|guidl|meth)__.*$ + has: ^doc_(getstrt|concept)__.*$ # Guidances gd_req: - title: "Process Requirements" - prefix: "gd_req__" + title: Process Requirements + prefix: gd_req__ mandatory_options: - id: "^gd_req__[0-9a-z_]*$" - status: "^(valid|draft)$" + id: ^gd_req__[0-9a-z_]*$ + status: ^(valid|draft)$ optional_links: - complies: "^std_req__(iso26262|isosae21434|isopas8926|aspice_40)__.*$" - satisfies: "^wf__.*$" + complies: ^std_req__(iso26262|isosae21434|isopas8926|aspice_40)__.*$ + satisfies: ^wf__.*$ gd_temp: - title: "Process Template" - prefix: "gd_temp__" + title: Process Template + prefix: gd_temp__ mandatory_options: - id: "^gd_temp__[0-9a-z_]*$" - status: "^(valid|draft)$" + id: ^gd_temp__[0-9a-z_]*$ + status: ^(valid|draft)$ optional_links: - complies: "std_req__(iso26262|isodae21434|isopas8926|aspice_40)__.*$" + complies: std_req__(iso26262|isodae21434|isopas8926|aspice_40)__.*$ gd_chklst: - title: "Process Checklist" - prefix: "gd_chklst__" + title: Process Checklist + prefix: gd_chklst__ mandatory_options: - id: "^gd_chklst__[0-9a-z_]*$" - status: "^(valid|draft)$" + id: ^gd_chklst__[0-9a-z_]*$ + status: ^(valid|draft)$ optional_links: - complies: "std_req__(iso26262|isodae21434|isopas8926|aspice_40)__.*$" + complies: std_req__(iso26262|isodae21434|isopas8926|aspice_40)__.*$ gd_guidl: - title: "Process Guideline" - prefix: "gd_guidl__" + title: Process Guideline + prefix: gd_guidl__ mandatory_options: - id: "^gd_guidl__[0-9a-z_]*$" - status: "^(valid|draft)$" + id: ^gd_guidl__[0-9a-z_]*$ + status: ^(valid|draft)$ optional_links: - complies: "std_req__(iso26262|isosae21434|isopas8926|aspice_40)__.*$" + complies: std_req__(iso26262|isosae21434|isopas8926|aspice_40)__.*$ gd_method: - title: "Process Method" - prefix: "gd_meth__" + title: Process Method + prefix: gd_meth__ mandatory_options: - id: "^gd_meth__[0-9a-z_]*$" - status: "^(valid|draft)$" + id: ^gd_meth__[0-9a-z_]*$ + status: ^(valid|draft)$ optional_links: - complies: "std_req__(iso26262|isosae21434|isopas8926|aspice_40)__.*$" + complies: std_req__(iso26262|isosae21434|isopas8926|aspice_40)__.*$ # S-CORE Workproduct workproduct: - title: "Workproduct" - prefix: "wp__" + title: Workproduct + prefix: wp__ mandatory_options: - id: "^wp__[0-9a-z_]*$" - status: "^(valid|draft)$" + id: ^wp__[0-9a-z_]*$ + status: ^(valid|draft)$ optional_links: - complies: "std_(wp__iso26262|wp__isosae21434|wp__isopas8926|iic_aspice_40)__.*$" + complies: std_(wp__iso26262|wp__isosae21434|wp__isopas8926|iic_aspice_40)__.*$ # Role role: - title: "Role" - prefix: "rl__" + title: Role + prefix: rl__ mandatory_options: - id: "^rl__[0-9a-z_]*$" + id: ^rl__[0-9a-z_]*$ optional_links: - contains: "^rl__.*$" + contains: ^rl__.*$ # Documents doc_concept: - title: "Concept Definition" - prefix: "doc_concept__" + title: Concept Definition + prefix: doc_concept__ mandatory_options: - id: "^doc_concept__[0-9a-z_]*$" - status: "^(valid|draft)$" + id: ^doc_concept__[0-9a-z_]*$ + status: ^(valid|draft)$ doc_getstrt: - title: "Getting Startet" - prefix: "doc_getstrt__" + title: Getting Startet + prefix: doc_getstrt__ mandatory_options: - id: "^doc_getstrt__[0-9a-z_]*$" - status: "^(valid|draft)$" + id: ^doc_getstrt__[0-9a-z_]*$ + status: ^(valid|draft)$ ############################################################################## # S-CORE Metamodel ############################################################################## # General document: - title: "Generic Document" - prefix: "doc__" + title: Generic Document + prefix: doc__ mandatory_options: - id: "^doc__[0-9a-z_]*$" - status: "^(valid|draft|invalid)$" + id: ^doc__[0-9a-z_]*$ + status: ^(valid|draft|invalid)$ optional_options: safety: "^(QM|ASIL_B|ASIL_D)$" security: "^(YES|NO)$" @@ -192,285 +193,286 @@ needs_types: # req-Id: gd_req__req__linkage # Requirements stkh_req: - title: "Stakeholder Requirement" - prefix: "stkh_req__" - mandatory_options: - id: "^stkh_req__[0-9a-z_]*$" - reqtype: "^(Functional|Interface|Process|Legal|Non-Functional)$" - safety: "^(QM|ASIL_B|ASIL_D)$" - status: "^(valid|invalid)$" - rationale: "^.+$" + # @satisfies(PROCESS_gd_req__req__structure) + title: Stakeholder Requirement + prefix: stkh_req__ + mandatory_options: + id: ^stkh_req__[0-9a-z_]*$ + reqtype: ^(Functional|Interface|Process|Legal|Non-Functional)$ + safety: ^(QM|ASIL_B|ASIL_D)$ + status: ^(valid|invalid)$ + rationale: ^.+$ optional_options: - security: "^(YES|NO)$" - codelink: "^.*$" - testlink: "^.*$" - reqcovered: "^(YES|NO)$" - testcovered: "^(YES|NO)$" - hash: "^.*$" + security: ^(YES|NO)$ + codelink: ^.*$ + testlink: ^.*$ + reqcovered: ^(YES|NO)$ + testcovered: ^(YES|NO)$ + hash: ^.*$ feat_req: - title: "Feature Requirement" - prefix: "feat_req__" - style: "node" - mandatory_options: - id: "^feat_req__[0-9a-z_]*$" - reqtype: "^(Functional|Interface|Process|Legal|Non-Functional)$" - security: "^(YES|NO)$" - safety: "^(QM|ASIL_B|ASIL_D)$" - status: "^(valid|invalid)$" + title: Feature Requirement + prefix: feat_req__ + style: node + mandatory_options: + id: ^feat_req__[0-9a-z_]*$ + reqtype: ^(Functional|Interface|Process|Legal|Non-Functional)$ + security: ^(YES|NO)$ + safety: ^(QM|ASIL_B|ASIL_D)$ + status: ^(valid|invalid)$ mandatory_links: # req-Id: gd_req__req__linkage_fulfill - satisfies: "^stkh_req__.*$" + satisfies: ^stkh_req__.*$ optional_options: - codelink: "^.*$" - testlink: "^.*$" - reqcovered: "^(YES|NO)$" - testcovered: "^(YES|NO)$" - hash: "^.*$" + codelink: ^.*$ + testlink: ^.*$ + reqcovered: ^(YES|NO)$ + testcovered: ^(YES|NO)$ + hash: ^.*$ comp_req: - title: "Component Requirement" - prefix: "comp_req__" - mandatory_options: - id: "^comp_req__[0-9a-z_]*$" - reqtype: "^(Functional|Interface|Process|Legal|Non-Functional)$" - security: "^(YES|NO)$" - safety: "^(QM|ASIL_B|ASIL_D)$" - status: "^(valid|invalid)$" + title: Component Requirement + prefix: comp_req__ + mandatory_options: + id: ^comp_req__[0-9a-z_]*$ + reqtype: ^(Functional|Interface|Process|Legal|Non-Functional)$ + security: ^(YES|NO)$ + safety: ^(QM|ASIL_B|ASIL_D)$ + status: ^(valid|invalid)$ mandatory_links: - satisfies: "^feat_req__.*$" + satisfies: ^feat_req__.*$ optional_options: - codelink: "^.*$" - testlink: "^.*$" - reqcovered: "^(YES|NO)$" - testcovered: "^(YES|NO)$" - hash: "^.*$" + codelink: ^.*$ + testlink: ^.*$ + reqcovered: ^(YES|NO)$ + testcovered: ^(YES|NO)$ + hash: ^.*$ tool_req: - title: "Tool Requirement" - prefix: "tool_req__" - mandatory_options: - id: "^tool_req__[0-9a-z_]*$" - reqtype: "^(Functional|Interface|Process|Legal|Non-Functional)$" - security: "^(YES|NO)$" - safety: "^(QM|ASIL_B|ASIL_D)$" - status: "^(valid|invalid)$" + title: Tool Requirement + prefix: tool_req__ + mandatory_options: + id: ^tool_req__[0-9a-z_]*$ + reqtype: ^(Functional|Interface|Process|Legal|Non-Functional)$ + security: ^(YES|NO)$ + safety: ^(QM|ASIL_B|ASIL_D)$ + status: ^(valid|invalid)$ mandatory_links: - satisfies: "^.*_req__.*$" + satisfies: ^.*_req__.*$ optional_options: - codelink: "^.*$" - testlink: "^.*$" - reqcovered: "^(YES|NO)$" - testcovered: "^(YES|NO)$" - hash: "^.*$" + codelink: ^.*$ + testlink: ^.*$ + reqcovered: ^(YES|NO)$ + testcovered: ^(YES|NO)$ + hash: ^.*$ + implemented: ^(YES|PARTIAL|NO)$ aou_req: - title: "Assumption of Use" - prefix: "aou_req__" - mandatory_options: - id: "^aou_req__[0-9a-z_]*$" - reqtype: "^(Functional|Interface|Process|Legal|Non-Functional)$" - security: "^(YES|NO)$" - safety: "^(QM|ASIL_B|ASIL_D)$" - status: "^(valid|invalid)$" + title: Assumption of Use + prefix: aou_req__ + mandatory_options: + id: ^aou_req__[0-9a-z_]*$ + reqtype: ^(Functional|Interface|Process|Legal|Non-Functional)$ + security: ^(YES|NO)$ + safety: ^(QM|ASIL_B|ASIL_D)$ + status: ^(valid|invalid)$ optional_options: - codelink: "^.*$" - testlink: "^.*$" - reqcovered: "^(YES|NO)$" - testcovered: "^(YES|NO)$" - hash: "^.*$" + codelink: ^.*$ + testlink: ^.*$ + reqcovered: ^(YES|NO)$ + testcovered: ^(YES|NO)$ + hash: ^.*$ optional_links: - mitigates: "^.*$" + mitigates: ^.*$ # Architecture feat_arc_sta: - title: "Feature Architecture Static View" - prefix: "feat_arc_sta__" - color: "#FEDCD2" - style: "card" - mandatory_options: - id: "^feat_arc_sta__[0-9a-z_]+$" - security: "^(YES|NO)$" - safety: "^(QM|ASIL_B|ASIL_D)$" - status: "^(valid|invalid)$" + title: Feature Architecture Static View + prefix: feat_arc_sta__ + color: #FEDCD2 + style: card + mandatory_options: + id: ^feat_arc_sta__[0-9a-z_]+$ + security: ^(YES|NO)$ + safety: ^(QM|ASIL_B|ASIL_D)$ + status: ^(valid|invalid)$ mandatory_links: - includes: "^logic_arc_int(_op)*__.+$" + includes: ^logic_arc_int(_op)*__.+$ optional_links: - fulfils: "^feat_req__.+$" + fulfils: ^feat_req__.+$ feat_arc_dyn: - title: "Feature Architecture Dynamic View" - prefix: "feat_arc_dyn__" - color: "#FEDCD2" - style: "card" - mandatory_options: - id: "^feat_arc_dyn__[0-9a-z_]+$" - security: "^(YES|NO)$" - safety: "^(QM|ASIL_B|ASIL_D)$" - status: "^(valid|invalid)$" + title: Feature Architecture Dynamic View + prefix: feat_arc_dyn__ + color: #FEDCD2 + style: card + mandatory_options: + id: ^feat_arc_dyn__[0-9a-z_]+$ + security: ^(YES|NO)$ + safety: ^(QM|ASIL_B|ASIL_D)$ + status: ^(valid|invalid)$ mandatory_links: - fulfils: "^feat_req__.+$" + fulfils: ^feat_req__.+$ logic_arc_int: - title: "Logical Architecture Interfaces" - prefix: "logic_arc_int__" - color: "#FEDCD2" - style: "card" - mandatory_options: - id: "^logic_arc_int__[0-9a-z_]+$" - security: "^(YES|NO)$" - safety: "^(QM|ASIL_B|ASIL_D)$" - status: "^(valid|invalid)$" + title: Logical Architecture Interfaces + prefix: logic_arc_int__ + color: #FEDCD2 + style: card + mandatory_options: + id: ^logic_arc_int__[0-9a-z_]+$ + security: ^(YES|NO)$ + safety: ^(QM|ASIL_B|ASIL_D)$ + status: ^(valid|invalid)$ optional_links: - includes: "^logic_arc_int_op__.+$" - fulfils: "^comp_req__.+$" + includes: ^logic_arc_int_op__.+$ + fulfils: ^comp_req__.+$ logic_arc_int_op: - title: "Logical Architecture Interface Operation" - prefix: "logic_arc_int_op__" - color: "#FEDCD2" - style: "card" - mandatory_options: - id: "^logic_arc_int_op__[0-9a-z_]+$" - security: "^(YES|NO)$" - safety: "^(QM|ASIL_B|ASIL_D)$" - status: "^(valid|invalid)$" + title: Logical Architecture Interface Operation + prefix: logic_arc_int_op__ + color: #FEDCD2 + style: card + mandatory_options: + id: ^logic_arc_int_op__[0-9a-z_]+$ + security: ^(YES|NO)$ + safety: ^(QM|ASIL_B|ASIL_D)$ + status: ^(valid|invalid)$ mandatory_links: - included_by: "^logic_arc_int__.+$" + included_by: ^logic_arc_int__.+$ mod_view_sta: - title: "Module Architecture Static View" - prefix: "mod_view_sta__" - color: "#FEDCD2" - style: "card" + title: Module Architecture Static View + prefix: mod_view_sta__ + color: #FEDCD2 + style: card mandatory_options: - id: "^mod_view_sta__[0-9a-z_]+$" + id: ^mod_view_sta__[0-9a-z_]+$ mandatory_links: - includes: "^comp_arc_sta__.+$" + includes: ^comp_arc_sta__.+$ mod_view_dyn: - title: "Module Architecture Dynamic View" - prefix: "mod_view_dyn__" - color: "#FEDCD2" - style: "card" + title: Module Architecture Dynamic View + prefix: mod_view_dyn__ + color: #FEDCD2 + style: card mandatory_options: - id: "^mod_view_dyn__[0-9a-z_]+$" + id: ^mod_view_dyn__[0-9a-z_]+$ comp_arc_sta: - title: "Component Architecture Static View" - prefix: "comp_arc_sta__" - color: "#FEDCD2" - style: "card" - mandatory_options: - id: "^comp_arc_sta__[0-9a-z_]+$" - security: "^(YES|NO)$" - safety: "^(QM|ASIL_B|ASIL_D)$" - status: "^(valid|invalid)$" + title: Component Architecture Static View + prefix: comp_arc_sta__ + color: #FEDCD2 + style: card + mandatory_options: + id: ^comp_arc_sta__[0-9a-z_]+$ + security: ^(YES|NO)$ + safety: ^(QM|ASIL_B|ASIL_D)$ + status: ^(valid|invalid)$ optional_links: - implements: "^real_arc_int(_op)*__.+$" - includes: "^comp_arc_sta__.+$" - uses: "^real_arc_int(_op)*__.+$" - fulfils: "^comp_req__.+$" + implements: ^real_arc_int(_op)*__.+$ + includes: ^comp_arc_sta__.+$ + uses: ^real_arc_int(_op)*__.+$ + fulfils: ^comp_req__.+$ comp_arc_dyn: - title: "Component Architecture Dynamic View" - prefix: "comp_arc_dyn__" - color: "#FEDCD2" - style: "card" - mandatory_options: - id: "^comp_arc_dyn__[0-9a-z_]+$" - security: "^(YES|NO)$" - safety: "^(QM|ASIL_B|ASIL_D)$" - status: "^(valid|invalid)$" + title: Component Architecture Dynamic View + prefix: comp_arc_dyn__ + color: #FEDCD2 + style: card + mandatory_options: + id: ^comp_arc_dyn__[0-9a-z_]+$ + security: ^(YES|NO)$ + safety: ^(QM|ASIL_B|ASIL_D)$ + status: ^(valid|invalid)$ optional_links: - fulfils: "^comp_req__.+$" + fulfils: ^comp_req__.+$ real_arc_int: - title: "Component Architecture Interfaces" - prefix: "real_arc_int__" - color: "#FEDCD2" - style: "card" - mandatory_options: - id: "^real_arc_int__[0-9a-z_]+$" - security: "^(YES|NO)$" - safety: "^(QM|ASIL_B|ASIL_D)$" - status: "^(valid|invalid)$" - language: "^(cpp|rust)$" + title: Component Architecture Interfaces + prefix: real_arc_int__ + color: #FEDCD2 + style: card + mandatory_options: + id: ^real_arc_int__[0-9a-z_]+$ + security: ^(YES|NO)$ + safety: ^(QM|ASIL_B|ASIL_D)$ + status: ^(valid|invalid)$ + language: ^(cpp|rust)$ optional_links: - fulfils: "^comp_req__.+$" + fulfils: ^comp_req__.+$ real_arc_int_op: - title: "Component Architecture Interface Operation" - prefix: "real_arc_int_op__" - color: "#FEDCD2" - style: "card" - mandatory_options: - id: "^real_arc_int_op__[0-9a-z_]+$" - security: "^(YES|NO)$" - safety: "^(QM|ASIL_B|ASIL_D)$" - status: "^(valid|invalid)$" + title: Component Architecture Interface Operation + prefix: real_arc_int_op__ + color: #FEDCD2 + style: card + mandatory_options: + id: ^real_arc_int_op__[0-9a-z_]+$ + security: ^(YES|NO)$ + safety: ^(QM|ASIL_B|ASIL_D)$ + status: ^(valid|invalid)$ mandatory_links: - included_by: "^real_arc_int__.+$" + included_by: ^real_arc_int__.+$ optional_links: - implements: "^logic_arc_int_op__.+$" - + implements: ^logic_arc_int_op__.+$ review_header: - prefix: "review__header" - title: "Review Header" + prefix: review__header + title: Review Header mandatory_options: - id: "^review__header__[0-9a-z_]*$" - reviewers: "^.*$" - approvers: "^.*$" - hash: "^.*$" - template: "^.*$" + id: ^review__header__[0-9a-z_]*$ + reviewers: ^.*$ + approvers: ^.*$ + hash: ^.*$ + template: ^.*$ # Implementation dd_sta: - title: "Static detailed design" - prefix: "dd_sta__" - color: "#FEDCD2" - style: "card" - mandatory_options: - id: "^dd_sta__[0-9a-z_]*$" - security: "^(YES|NO)$" - safety: "^(QM|ASIL_B|ASIL_D)$" - status: "^(valid|invalid)$" + title: Static detailed design + prefix: dd_sta__ + color: #FEDCD2 + style: card + mandatory_options: + id: ^dd_sta__[0-9a-z_]*$ + security: ^(YES|NO)$ + safety: ^(QM|ASIL_B|ASIL_D)$ + status: ^(valid|invalid)$ mandatory_links: - implements: "^comp_req__.*$" - satisfies: "^comp_arc_sta__.*$" + implements: ^comp_req__.*$ + satisfies: ^comp_arc_sta__.*$ optional_links: - includes: "^sw_unit__.*$" + includes: ^sw_unit__.*$ dd_dyn: - title: "Dynamic detailed design" - prefix: "dd_dyn__" - color: "#FEDCD2" - style: "card" - mandatory_options: - id: "^dd_dyn__[0-9a-z_]*$" - security: "^(YES|NO)$" - safety: "^(QM|ASIL_B|ASIL_D)$" - status: "^(valid|invalid)$" + title: Dynamic detailed design + prefix: dd_dyn__ + color: #FEDCD2 + style: card + mandatory_options: + id: ^dd_dyn__[0-9a-z_]*$ + security: ^(YES|NO)$ + safety: ^(QM|ASIL_B|ASIL_D)$ + status: ^(valid|invalid)$ mandatory_links: - implements: "^comp_req__.*$" - satisfies: "^comp_arc_sta__.*$" + implements: ^comp_req__.*$ + satisfies: ^comp_arc_sta__.*$ sw_unit: - title: "Software unit" - prefix: "sw_unit__" + title: Software unit + prefix: sw_unit__ mandatory_options: - id: "^sw_unit__[0-9a-z_]*$" - security: "^(YES|NO)$" - safety: "^(QM|ASIL_B|ASIL_D)$" - status: "^(valid|invalid)$" + id: ^sw_unit__[0-9a-z_]*$ + security: ^(YES|NO)$ + safety: ^(QM|ASIL_B|ASIL_D)$ + status: ^(valid|invalid)$ sw_unit_int: - title: "Software unit interfaces" - prefix: "sw_unit_int__" - color: "#FEDCD2" - style: "card" + title: Software unit interfaces + prefix: sw_unit_int__ + color: #FEDCD2 + style: card mandatory_options: - id: "^sw_unit_int__[0-9a-z_]*$" - security: "^(YES|NO)$" - safety: "^(QM|ASIL_B|ASIL_D)$" - status: "^(valid|invalid)$" + id: ^sw_unit_int__[0-9a-z_]*$ + security: ^(YES|NO)$ + safety: ^(QM|ASIL_B|ASIL_D)$ + status: ^(valid|invalid)$ # Extra link types, which shall be available and allow need types to be linked to each other. # We use a dedicated linked type for each type of a connection, for instance from @@ -483,67 +485,67 @@ needs_extra_links: ############################################################## # Workflow contains: - incoming: "contained by" - outgoing: "contains" + incoming: contained by + outgoing: contains has: - incoming: "relates to" - outgoing: "has" + incoming: relates to + outgoing: has input: - incoming: "is input to" - outgoing: "needs input" + incoming: is input to + outgoing: needs input output: - incoming: "is output from" - outgoing: "outputs" + incoming: is output from + outgoing: outputs # Roles responsible: - incoming: "is responsible for" - outgoing: "responsible" + incoming: is responsible for + outgoing: responsible approved_by: - incoming: "approves" - outgoing: "approved by" + incoming: approves + outgoing: approved by supported_by: - incoming: "supports" - outgoing: "supported by" + incoming: supports + outgoing: supported by # Workproduct complies: - incoming: "complies to" - outgoing: "complies" + incoming: complies to + outgoing: complies ############################################################## # S-CORE Metamodel ############################################################## # Requirements satisfies: - incoming: "satisfied by" - outgoing: "satisfies" + incoming: satisfied by + outgoing: satisfies # Architecture fulfils: - incoming: "fulfilled by" - outgoing: "fulfils" + incoming: fulfilled by + outgoing: fulfils implements: - incoming: "implemented by" - outgoing: "implements" + incoming: implemented by + outgoing: implements uses: - incoming: "used by" - outgoing: "uses" + incoming: used by + outgoing: uses includes: - incoming: "included by" - outgoing: "includes" + incoming: included by + outgoing: includes included_by: - incoming: "includes" - outgoing: "included by" + incoming: includes + outgoing: included by ############################################################## # Graph Checks # The graph checks focus on the relation of the needs and their attributes. @@ -552,7 +554,7 @@ needs_extra_links: # needs:defines the needs types to which the check should be applied # - [include / exclude]: need types to which the check should be applied; # multiple need types can be defined by separating them with a comma; -# to perform the check on all needs types, set include to "." +# to perform the check on all needs types, set include to . # - condition: defines (together with apply) the condition which the needs need to fulfill # - [and / or / xor / not] # - check: defines the check that should be applied @@ -566,32 +568,32 @@ graph_checks: # req-Id: gd_req__req__linkage_safety req_safety_linkage: needs: - include: "comp_req, feat_req" + include: comp_req, feat_req condition: and: - - "safety != QM" - - "status == valid" + - safety != QM + - status == valid check: satisfies: and: - - "safety != QM" - - "status == valid" + - safety != QM + - status == valid req_linkage: needs: - include: "comp_req, feat_req" - condition: "status == valid" + include: comp_req, feat_req + condition: status == valid check: - satisfies: "status == valid" + satisfies: status == valid # req-Id: gd_req__req__linkage_architecture arch_safety_linkage: needs: - include: "comp_req, feat_req" + include: comp_req, feat_req condition: and: - - "safety != QM" - - "status == valid" + - safety != QM + - status == valid check: fulfils: and: - - "safety != QM" - - "status == valid" + - safety != QM + - status == valid diff --git a/src/incremental.py b/src/incremental.py index 90e9ff8..de5456d 100644 --- a/src/incremental.py +++ b/src/incremental.py @@ -35,27 +35,6 @@ def get_env(name: str) -> str: return val -def transform_env_str_to_dict(external_needs_source: str) -> list[dict[str, str]]: - """ - Transforms the 'string' we get from 'docs.bzl' back into something we can parse easliy inside sphinx/python - !! HACK: This truly isn't great !! - """ - transformed_dicts: list[dict[str, str]] = [] - dict_list = [ - x.split(",") - for x in external_needs_source.replace("]", "") - .replace("[", "") - .replace("{", "") - .split("}") - ] - for inner_dict in dict_list: - kv_splits = [kv.split(":", 1) for kv in inner_dict if len(inner_dict) > 1] - single_dict = {key_value[0]: key_value[1] for key_value in kv_splits} - if single_dict: - transformed_dicts.append(single_dict) - return transformed_dicts - - if __name__ == "__main__": # Add debuging functionality parser = argparse.ArgumentParser() @@ -94,7 +73,7 @@ def transform_env_str_to_dict(external_needs_source: str) -> list[dict[str, str] "auto", "--conf-dir", get_env("CONF_DIRECTORY"), - f"--define=external_needs_source={json.dumps(transform_env_str_to_dict(get_env('EXTERNAL_NEEDS_INFO')))}", + f"--define=external_needs_source={get_env('EXTERNAL_NEEDS_INFO')}", ] # configure sphinx build with GitHub user and repo from CLI