diff --git a/docs/features/feature_example/architecture/index.rst b/docs/features/feature_example/architecture/index.rst index f128e5e3..9789b649 100644 --- a/docs/features/feature_example/architecture/index.rst +++ b/docs/features/feature_example/architecture/index.rst @@ -101,32 +101,6 @@ Logical Interfaces The logical interfaces of the feature are defined in the `logical interfaces` section of the feature documentation in the project repository. -Module Viewpoint ----------------- - -The following modules are needed to be defined to be able to draw the static feature view. -They will be replaced by linking the proper module definitions in the used module's repositories as soon as those exist. - -The rendered module and used-component examples are maintained in the -`module template documentation `_. - -.. code-block:: rst - - .. mod:: Module Name - :id: mod__module_name - :includes: comp__component_name_template - - - .. mod_view_sta:: Module Name Static View - :id: mod_view_sta__feature_name__module_name - :includes: comp__component_name_template - - .. needarch:: - :scale: 50 - :align: center - - {{ draw_module(need(), needs) }} - Used Components --------------- diff --git a/docs/manuals/api_description/.gitkeep b/docs/manuals/api_description/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/manuals/config/.gitkeep b/docs/manuals/config/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/manuals/examples/.gitkeep b/docs/manuals/examples/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/manuals/index.rst b/docs/manuals/index.rst index 8890d44c..87adad05 100644 --- a/docs/manuals/index.rst +++ b/docs/manuals/index.rst @@ -18,5 +18,6 @@ Manuals .. toctree:: :titlesonly: + user_manuel safety_manual security_manual diff --git a/docs/manuals/performance/.gitkeep b/docs/manuals/performance/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/manuals/user_manuel.rst b/docs/manuals/user_manuel.rst new file mode 100644 index 00000000..cbb49c18 --- /dev/null +++ b/docs/manuals/user_manuel.rst @@ -0,0 +1,274 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +.. _user_manual: + +User Manual +########### + + +.. attention:: + Update the document metadata according to your needs, particularly linking to the corresponding + work package with the ``realizes`` field once work packages are defined. + +Overview +======== + +This user manual provides comprehensive guidance for using the [Your Module Name] module. +It covers installation, configuration, basic usage, and best practices for integrating this module +into your project. + +.. note:: + This is a template user manual. Replace placeholder text with actual module-specific information. + +Feature List +============ + +Key features of this module: + +* Feature overview and navigation: :doc:`/docs/features/index` +* Feature template and scope example: :doc:`/docs/features/feature_example/index` +* Feature architecture and verification artifacts: :doc:`/docs/features/feature_example/architecture/index` +* Feature safety artifacts (FMEA, DFA, AoU): :doc:`/docs/features/feature_example/safety_analysis/fmea`, :doc:`/docs/features/feature_example/safety_analysis/dfa`, and :doc:`/docs/features/feature_example/safety_analysis/aou_requirements_template` +* Feature security artifacts: :doc:`/docs/features/feature_example/security_analysis/index` +* Feature planning artifacts (safety/security): :doc:`/docs/features/feature_example/safety_planning/index` and :doc:`/docs/features/feature_example/security_planning/index` + +Platform Requirements +===================== + +Supported Platforms +------------------- + +* **C++**: C++17 or later +* **Rust**: 1.70 or later (if Rust support is included) +* **Build System**: Bazel 6.0 or later +* **Operating Systems**: Linux, macOS, Windows (as applicable) + +Dependencies +------------ + +[List key external dependencies, licenses, and version requirements] + +**Example:** +* Standard library (STL/Core) +* [Other required libraries] + +Quick Start - Building and Testing +=================================== + +Building the Module +-------------------- + +To build the entire module: + +.. code-block:: bash + + bazel build //src/... + +Running Tests +-------------- + +To run all tests: + +.. code-block:: bash + + bazel test //... + +To run only unit tests: + +.. code-block:: bash + + bazel test //src/... + +To run component or feature integration tests: + +.. code-block:: bash + + bazel test //tests/... + +Module Configuration Details +============================= + +The ``project_config.bzl`` file at the root of the module defines metadata used by Bazel macros. +This file controls build behavior and project-specific settings. + +Configuration Example +--------------------- + +.. code-block:: python + + PROJECT_CONFIG = { + "asil_level": "QM", + "source_code": ["cpp", "rust"] + } + +Configuration Effects +--------------------- + +The configuration enables conditional build behavior: + +* **Language-specific tools**: For C++ code, tools like ``clang-tidy`` are used; for Rust code, ``clippy`` is used +* **Safety level**: The ASIL level affects safety-related build settings and validation +* **Source code languages**: The build system optimizes for the configured languages + +Getting Started with Features and Components +============================================ + +Feature Documentation +--------------------- + +For documentation on features implemented in the module: + +.. toctree:: + :maxdepth: 1 + + /docs/features/index + +Component Documentation +----------------------- + +For documentation of individual components within this module: + +.. toctree:: + :maxdepth: 1 + + /score/component_example/docs/index + +Examples +-------- + +Useful examples and tutorials: + +.. toctree:: + :maxdepth: 1 + + /examples/docs/architecture_modeling_example + +Integration Guidelines +====================== + +Integrating with Your Project +------------------------------ + +1. Add the module to your Bazel workspace: + + .. code-block:: python + + # In your MODULE.bazel + bazel_dep(name = "module_template", version = "1.0") + +2. Reference in your build files: + + .. code-block:: python + + cc_library( + name = "my_target", + deps = ["@module_template//score/component_example:component"], + ) + +3. Include headers and compile your code + +Best Practices +-------------- + +* Always validate input parameters +* Handle error codes and exceptions appropriately +* Use the module in accordance with safety and security guidelines +* Review the safety manual (wp__module_safety_manual) for safety-critical applications +* Review the security manual (wp__module_security_manual) for security considerations + +API Reference +============= + +For complete API documentation and descriptions, refer to the API documentation in the ``api_description/`` directory. + +Performance Considerations +========================== + +This section covers performance characteristics, optimization strategies, and resource requirements. +Refer to the ``performance/`` directory for detailed performance guides and benchmarks. + +Troubleshooting +=============== + +Common Issues and Solutions +---------------------------- + +**Issue: Build fails with undefined reference** + + Check that all dependencies are properly declared in your BUILD file and that the module is correctly linked. + +**Issue: Runtime errors or crashes** + + Verify that: + * You are using the module API correctly (refer to API Reference) + * All required initialization steps have been completed + * Input data meets the documented requirements + +**Issue: Performance problems** + + Consult the Performance Considerations section or review the ``performance/`` documentation. + +Getting Help +============ + +For additional support and resources: + +* Review the API Reference documentation +* Check the configuration examples in the ``config/`` folder +* Refer to example implementations in ``examples/`` +* Consult the Safety Manual for safety-critical usage +* Consult the Security Manual for security-related concerns +* Contact the module maintainers or community forums + +Safety and Security +=================== + +**Safety-Critical Usage**: If you are using this module in a safety-critical context, +please refer to :doc:`safety_manual` for detailed safety requirements and guidelines. + +**Security Considerations**: For information about security aspects and requirements, +please refer to :doc:`security_manual`. + +Known Limitations +================= + +* [Limitation 1] +* [Limitation 2] +* [Known issues and workarounds] + +Version History and Compatibility +================================== + +[Document version changes, API stability, deprecation notices, and migration guides] + +**Current Version**: 1.0 (Draft) + +Compatibility Notes +------------------- + +* Backward compatibility with previous versions: [Yes/No/Partial] +* Migration guide for [previous version] users: [Link or reference] + +License +======= + +This module is licensed under the Apache License Version 2.0. +See the LICENSE file in the repository for full license text. + +Feedback and Contributions +========================== + +Your feedback and contributions are welcome! Please report issues or suggestions through the +project's issue tracker or contribute directly to the repository. diff --git a/index.rst b/index.rst index 6422a728..568fb92c 100644 --- a/index.rst +++ b/index.rst @@ -27,7 +27,7 @@ Overview This repository provides a standardized setup for projects using **C++** or **Rust** and **Bazel** as a build system. It integrates best practices for build, test, CI/CD and documentation. It also provides an example of modeling architecture in Sphinx Needs in :doc:`/examples/docs/architecture_modeling_example`. -It also provides the component architecture template snippets in :doc:`/score/component_example/docs/architecture/component_architecture_template`. +It also provides the component architecture template snippets in :doc:`/score/component_example/docs/architecture/component_architecture`. It also provides an example of documenting detailed design in :doc:`/score/component_example/docs/detailed_design/detailed_design_example`. Module Layout @@ -48,10 +48,16 @@ The module template includes the following top-level structure: │ │ ├── safety_planning/ # Feature safety planning artifacts │ │ ├── security_analysis/ # Feature security analysis artifacts [wp__feature_security_analysis] │ │ └── security_planning/ # Feature security planning artifacts - │ ├── manuals/ # Module manual, integration manual, table of assumptions of use, - │ │ # safety manual [wp__module_safety_manual], - │ │ # needs table of [wp__requirements_feat_aou] - │ │ # security manual [wp__module_security_manual] + │ ├── manuals/ # Module manual, integration manual, table of assumptions of use + │ │ | # safety manual [wp__module_safety_manual], + │ │ | # needs table of [wp__requirements_feat_aou] + │ │ | # security manual [wp__module_security_manual] + │ │ │ # Additional optional user centric documentation (e.g. configuration guide, + │ │ │ # examples user guide, APIs & usage, performance analysis) + │ │ ├── config/ # Configuration guide (optional) + │ │ ├── examples/ # Examples user guide (optional) + │ │ ├── api_description/ # API detail description (optional) + │ │ └── performance/ # Performance analysis (optional) │ ├── release/ # Module release note [wp__module_sw_release_note] │ ├── safety_mgt/ # Module safety plan [wp__module_safety_plan], │ │ # module safety package [wp__module_safety_package], @@ -112,9 +118,15 @@ For identification of the single feature, the repository name or module name sho │ ├── security_analysis/ # Feature security analysis artifacts [wp__feature_security_analysis] │ ├── security_planning/ # Feature security planning artifacts │ ├── manuals/ # Module manual, integration manual, table of assumptions of use, - │ │ # safety manual [wp__module_safety_manual], - │ │ # needs table of [wp__requirements_feat_aou] - │ │ # security manual [wp__module_security_manual] + │ │ | # safety manual [wp__module_safety_manual], + │ │ | # needs table of [wp__requirements_feat_aou] + │ │ | # security manual [wp__module_security_manual] + │ │ | # Additional optional user centric documentation (e.g. configuration guide, + │ │ | # examples user guide, APIs & usage, performance analysis) + │ │ ├── config/ # Configuration guide (optional) + │ │ ├── examples/ # Examples user guide (optional) + │ │ ├── api_description/ # APIs detail description (optional) + │ │ └── performance/ # Performance analysis (optional) │ ├── release/ # Module release note [wp__module_sw_release_note] │ ├── safety_mgt/ # Module safety plan [wp__module_safety_plan], │ │ # module safety package [wp__module_safety_package], @@ -150,83 +162,40 @@ For identification of the single feature, the repository name or module name sho ├── project_config.bzl # Project metadata used by Bazel macros └── README.md # Entry point of the repository -Module / Feature Documentation ------------------------------- - -.. toctree:: - :maxdepth: 1 - - docs/features/index - docs/manuals/index - docs/release/release_note - docs/safety_mgt/index - docs/security_mgt/index - docs/verification_report/module_verification_report - -Component documentation -------------------------------- - -.. toctree:: - :maxdepth: 1 - - score/component_example/docs/index - score/component_example/docs/architecture/index - score/component_example/docs/detailed_design/index - score/component_example/docs/requirements/index - score/component_example/docs/safety_analysis/dfa - score/component_example/docs/safety_analysis/fmea - score/component_example/docs/safety_analysis/aou_requirements_template - score/component_example/docs/component_classification - -Examples --------- - -.. toctree:: - :maxdepth: 1 - - /examples/docs/architecture_modeling_example - - - -Quick Start ------------ - -To build the module: - -.. code-block:: bash - - bazel build //src/... - -To run all tests: - -.. code-block:: bash - - bazel test //... - -To run Unit Tests: +Module Documentation +-------------------- -.. code-block:: bash + - bazel test //src/... + -To run Component / Feature Integration Tests: +.. code-block:: rst -.. code-block:: bash + .. mod:: Module Name + :id: mod__module_name + :includes: comp__component_name_template - bazel test //tests/... -Module Configuration --------------------- + .. mod_view_sta:: Module Name Static View + :id: mod_view_sta__feature_name__module_name + :includes: comp__component_name_template -The `project_config.bzl` file defines metadata used by Bazel macros. + .. needarch:: + :scale: 50 + :align: center -Example: + {{ draw_module(need(), needs) }} -.. code-block:: python - PROJECT_CONFIG = { - "asil_level": "QM", - "source_code": ["cpp", "rust"] - } +.. toctree:: + :maxdepth: 1 -This enables conditional behavior (e.g., choosing `clang-tidy` for C++ or `clippy` for Rust). + docs/manuals/index + docs/release/release_note + docs/safety_mgt/index + docs/security_mgt/index + docs/verification_report/module_verification_report diff --git a/score/component_example/docs/architecture/component_architecture.rst b/score/component_example/docs/architecture/component_architecture.rst new file mode 100644 index 00000000..b3063346 --- /dev/null +++ b/score/component_example/docs/architecture/component_architecture.rst @@ -0,0 +1,142 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Component Architecture Documentation +==================================== + +.. document:: [Your Component Name] Architecture + :id: doc__mod_temp_component_name_architecture + :status: draft + :safety: ASIL_B + :security: NO + :realizes: wp__component_arch + :tags: template + +.. attention:: + The above directive must be updated according to your needs. + + - Modify ``Your Component Name`` to be your Component Name + - Modify ``id`` to be your Component Name in upper snake case preceded by ``doc__`` and followed by ``_architecture`` + - Adjust ``status`` to be ``valid`` + - Adjust ``safety`` and ``tags`` according to your needs + + +Overview +-------- + + + +Requirements Linked to Component Architecture +--------------------------------------------- + +.. code-block:: none + + .. needtable:: Overview of Component Requirements + :style: table + :columns: title;id + :filter: search("comp_arch_sta__archdes$", "fulfils_back") + :colwidths: 70,30 + +Description +----------- + + + + + + + +Rationale Behind Architecture Decomposition +******************************************* + +Mandatory: A motivation for the decomposition or reason for not further splitting it into internal components. + +.. note:: Common decisions across components / cross cutting concepts is at the higher level. + +Static Architecture +------------------- + +The components are designed to cover the expectations from the feature architecture +(i.e. if already exists a definition it should be taken over and enriched). + +A component can optional also consist of lower level components to further structure the architecture. The component and its static views can also optionally use interfaces provided by other components. + +.. comp:: Component Name + :id: comp__mod_temp_component_name_template + :security: YES + :safety: ASIL_B + :status: valid + :consists_of: comp__mod_temp_archex_sub_component_1, comp__mod_temp_archex_sub_component_2, comp__mod_temp_archex_sub_component_3 + :belongs_to: feat__mtef + +.. comp_arc_sta:: Component Name (Static View) + :id: comp_arc_sta__mod_temp_component_name__sv + :security: YES + :safety: ASIL_B + :status: valid + :belongs_to: comp__mod_temp_component_name_template + :fulfils: comp_req__mod_temp_component_name__some_title + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_component(need(), needs) }} + +Dynamic Architecture +-------------------- + +.. comp_arc_dyn:: Dynamic View + :id: comp_arc_dyn__mod_temp_component_name__dv + :security: YES + :safety: ASIL_B + :status: valid + :belongs_to: comp__mod_temp_component_name_template + :fulfils: comp_req__mod_temp_component_name__some_title + + Put here a sequence diagram + +Interfaces +---------- + +.. code-block:: rst + + .. real_arc_int:: + :id: real_arc_int__<component>__<Title> + :security: <YES|NO> + :safety: <QM|ASIL_B> + :fulfils: <link to component requirement id> + :language: cpp + +Internal Components +------------------- + +.. comp_arc_sta:: Component Name Static View + :id: comp_arc_sta__mod_temp_component_name__2 + :status: valid + :safety: ASIL_B + :security: YES + :fulfils: comp_req__mod_temp_component_name__some_title + :belongs_to: comp__mod_temp_component_example_2 + + No architecture but detailed design + +.. note:: + Architecture can be split into multiple files. At component level the public interfaces to be used by the user and tester to be shown. + +.. attention:: + The above directives must be updated according to your component architecture. + + - Replace the example content by the real content (according to :need:`gd_guidl__arch_design`) + - Set the status to valid and start the review/merge process diff --git a/score/component_example/docs/architecture/component_architecture_template.rst b/score/component_example/docs/architecture/component_architecture_template.rst deleted file mode 100644 index 419b4406..00000000 --- a/score/component_example/docs/architecture/component_architecture_template.rst +++ /dev/null @@ -1,124 +0,0 @@ -.. - # ******************************************************************************* - # 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 - # ******************************************************************************* - -Component Architecture Template -=============================== - -This page contains the component architecture template snippets that belong to the -module template repository. - -Overview --------- - -Use these snippets as the starting point for documenting component architecture in -the module template. - -Static Architecture -------------------- - -.. code-block:: rst - - .. comp:: Component Name - :id: comp__mod_temp_component_name_template - :security: YES - :safety: ASIL_B - :status: invalid - :implements: logic_arc_int__feature_name__interface_name1 - :consists_of: comp__component_name_internal_1, comp__component_name_internal_2, comp__component_name_internal_3 - :belongs_to: feat__feature_name - - .. comp_arc_sta:: Component Name (Static View) - :id: comp_arc_sta__mod_temp_component_name__sv - :security: YES - :safety: ASIL_B - :status: invalid - :belongs_to: comp__mod_temp_component_name_template - :uses: logic_arc_int__feature_name__interface_name1 - :fulfils: comp_req__mod_temp_component_name__some_title - - .. needarch:: - :scale: 50 - :align: center - - {{ draw_component(need(), needs) }} - -Dynamic Architecture --------------------- - -.. code-block:: rst - - .. comp_arc_dyn:: Dynamic View - :id: comp_arc_dyn__mod_temp_component_name__dv - :security: YES - :safety: ASIL_B - :status: invalid - :belongs_to: comp__mod_temp_component_name_template - :fulfils: comp_req__mod_temp_component_name__some_title - - Put here a sequence diagram - -Component Interface -------------------- - -The rendered component-interface example is maintained here so the module template -repository owns the live ``real_arc_int`` example. - -.. real_arc_int:: Component Interface 1 - :id: real_arc_int__mod_temp_component_name__if_1 - :status: valid - :safety: ASIL_B - :security: NO - :language: cpp - - .. needarch:: - :scale: 50 - :align: center - - {{ draw_interface(need(), needs)}} - -Internal Components -------------------- - -.. code-block:: rst - - .. comp_arc_sta:: Component Name Static View - :id: comp_arc_sta__mod_temp_component_name__2 - :status: invalid - :safety: ASIL_B - :security: YES - :fulfils: comp_req__mod_temp_component_name__some_title - :belongs_to: comp__mod_temp_component_name_template - - No architecture but detailed design - - .. comp:: Internal Component 1 - :id: comp__component_name_internal_1 - :status: invalid - :safety: ASIL_B - :security: YES - :belongs_to: feat__feature_name - - .. comp:: Internal Component 2 - :id: comp__component_name_internal_2 - :status: invalid - :safety: ASIL_B - :security: YES - :belongs_to: feat__feature_name - - .. comp:: Internal Component 3 - :id: comp__component_name_internal_3 - :status: invalid - :safety: ASIL_B - :security: YES - :belongs_to: feat__feature_name diff --git a/score/component_example/docs/architecture/index.rst b/score/component_example/docs/architecture/index.rst index cd63b36d..3ea0100b 100644 --- a/score/component_example/docs/architecture/index.rst +++ b/score/component_example/docs/architecture/index.rst @@ -17,146 +17,7 @@ Component Architecture ====================== -.. document:: [Your Component Name] Architecture - :id: doc__mod_temp_component_name_architecture - :status: draft - :safety: ASIL_B - :security: NO - :realizes: wp__component_arch - :tags: template - -.. attention:: - The above directive must be updated according to your needs. - - - Modify ``Your Component Name`` to be your Component Name - - Modify ``id`` to be your Component Name in upper snake case preceded by ``doc__`` and followed by ``_architecture`` - - Adjust ``status`` to be ``valid`` - - Adjust ``safety`` and ``tags`` according to your needs - -Overview --------- -<Brief summary> - -Requirements Linked to Component Architecture ---------------------------------------------- - -.. code-block:: none - - .. needtable:: Overview of Component Requirements - :style: table - :columns: title;id - :filter: search("comp_arch_sta__archdes$", "fulfils_back") - :colwidths: 70,30 - -Description ------------ - -<General Description> - -<Design Decisions - For the documentation of the decision the :need:`gd_temp__change_decision_record` can be used.> - -<Design Constraints> - -Rationale Behind Architecture Decomposition -******************************************* - -Mandatory: A motivation for the decomposition or reason for not further splitting it into internal components. - -.. note:: Common decisions across components / cross cutting concepts is at the higher level. - -Static Architecture -------------------- - -The components are designed to cover the expectations from the feature architecture -(i.e. if already exists a definition it should be taken over and enriched). - -A component can optional also consist of lower level components to further structure the architecture. The component and its static views can also optionally use interfaces provided by other components. - -.. comp:: Component Name - :id: comp__mod_temp_component_name_template - :security: YES - :safety: ASIL_B - :status: valid - :consists_of: comp__mod_temp_archex_sub_component_1, comp__mod_temp_archex_sub_component_2, comp__mod_temp_archex_sub_component_3 - :belongs_to: feat__mtef - -.. comp_arc_sta:: Component Name (Static View) - :id: comp_arc_sta__mod_temp_component_name__sv - :security: YES - :safety: ASIL_B - :status: valid - :belongs_to: comp__mod_temp_component_name_template - :fulfils: comp_req__mod_temp_component_name__some_title - - .. needarch:: - :scale: 50 - :align: center - - {{ draw_component(need(), needs) }} - -Dynamic Architecture --------------------- - -.. comp_arc_dyn:: Dynamic View - :id: comp_arc_dyn__mod_temp_component_name__dv - :security: YES - :safety: ASIL_B - :status: valid - :belongs_to: comp__mod_temp_component_name_template - :fulfils: comp_req__mod_temp_component_name__some_title - - Put here a sequence diagram - - -Interfaces ----------- - -.. code-block:: rst - - .. real_arc_int:: <Title> - :id: real_arc_int__<component>__<Title> - :security: <YES|NO> - :safety: <QM|ASIL_B> - :fulfils: <link to component requirement id> - :language: cpp - -Internal Components -------------------- - -.. comp_arc_sta:: Component Name Static View - :id: comp_arc_sta__mod_temp_component_name__2 - :status: valid - :safety: ASIL_B - :security: YES - :fulfils: comp_req__mod_temp_component_name__some_title - :belongs_to: comp__mod_temp_component_example_2 - - No architecture but detailed design - -.. note:: - Architecture can be split into multiple files. At component level the public interfaces to be used by the user and tester to be shown. - -.. attention:: - The above directives must be updated according to your component architecture. - - - Replace the example content by the real content (according to :need:`gd_guidl__arch_design`) - - Set the status to valid and start the review/merge process - -Component Architecture Template -------------------------------- - - A component architecture template is available to be used as a starting point for the documentation of the component architecture. It includes the main sections and example content to be adapted according to the real component architecture. - -.. toctree:: - - component_architecture_template - - -Architecture Checklist ----------------------- - -See following architecture inspection checklist for verification of the architecture. - .. toctree:: + component_architecture chklst_arc_inspection diff --git a/score/component_example/docs/index.rst b/score/component_example/docs/index.rst index a4ad7250..2902f98b 100644 --- a/score/component_example/docs/index.rst +++ b/score/component_example/docs/index.rst @@ -27,8 +27,19 @@ :realizes: wp__cmpt_request :tags: template +.. code-block:: rst + + .. comp:: Component Name + :id: comp__mod_temp_component_name_template + :security: YES + :safety: ASIL_B + :status: invalid + :implements: logic_arc_int__feature_name__interface_name1 + :consists_of: comp__component_name_internal_1, comp__component_name_internal_2, comp__component_name_internal_3 + :belongs_to: feat__feature_name + .. attention:: - The above directive must be updated according to your Component. + The above directives must be updated according to your Component. - Modify ``document`` to be your Component Name - Modify ``id`` to be your Component Name in upper snake case preceded by ``doc__`` @@ -56,7 +67,6 @@ Specification [Describe the requirements, architecture of any component.] or - Backwards Compatibility ======================= @@ -149,3 +159,20 @@ Footnotes ========= [A collection of footnotes cited in the CR, and a place to list non-inline hyperlink targets.] + + +Further Documentation of the component can be found in the following sections: + +Component Detail Information +============================ + +.. toctree:: + :maxdepth: 1 + + architecture/index + detailed_design/index + requirements/index + safety_analysis/dfa + safety_analysis/fmea + safety_analysis/aou_requirements_template + component_classification diff --git a/score/component_example/docs/requirements/index.rst b/score/component_example/docs/requirements/index.rst index 17785ce4..9eea1fc7 100644 --- a/score/component_example/docs/requirements/index.rst +++ b/score/component_example/docs/requirements/index.rst @@ -15,97 +15,7 @@ Requirements ############ -.. document:: [Your Component Name] Requirements - :id: doc__mod_temp_component_name_requirements - :status: draft - :safety: ASIL_B - :security: YES - :realizes: wp__requirements_comp - :tags: template - -.. attention:: - The above directive must be updated according to your Component. - - - Modify ``Your Component Name`` to be your Component Name - - Modify ``id`` to be your Component Name in upper snake case preceded by ``doc__`` and followed by ``_requirements`` - - Adjust ``status`` to be ``valid`` - - Adjust ``safety``, ``security`` and ``tags`` according to your needs - -<Headlines (for the list of requirements if structuring is needed)> -=================================================================== - -Component Requirements ----------------------- - -.. comp_req:: Some Title - :id: comp_req__mod_temp_component_name__some_title - :reqtype: Process - :security: YES - :safety: ASIL_B - :derived_from: feat_req__example_feature__example_req - :status: valid - :satisfied_by: comp__mod_temp_component_name_template - - The Component shall do xyz to another component to bring it to this condition at this time - - Note: (optional, not to be verified) - -.. attention:: - The above directive must be updated according to your component requirements. - - - Replace the example content by the real content for your first requirement - - Set ``derived_from`` with links to Feature requirements - - Set ``satisfied_by`` with a link to the right Component id - - Set ``safety`` and ``security`` to the right value - - Set the status to valid and start the review/merge process - - Add other needed requirements for your component - -Assumption of Use Requirements ------------------------------- - -.. aou_req:: Next Title - :id: aou_req__mod_temp_component_name__next_title - :reqtype: Process - :security: YES - :safety: ASIL_B - :status: valid - - The Component User shall do xyz to use the component safely/securely - -Environmental Requirements --------------------------- - -.. aou_req:: Another Title - :id: aou_req__mod_temp_component_name__another - :reqtype: Process - :security: YES - :safety: ASIL_B - :status: invalid - :tags: environment - - The Component shall only be used in a xyz environment to ensure its proper functioning. - -Hints ------ - -.. attention:: - The above directives must be updated according to your feature requirements. - - - Replace the example content by the real content for your first requirement (according to :need:`gd_guidl__req_engineering`) - - Set ``safety`` and ``security`` to the right value (ASIL B/QM; YES/NO) - - Set ``reqtype`` with a link to the right value (<Functional|Interface|Process|Non-Functional>) - - Add other needed requirements for your feature - - Set ``status`` to ``valid`` and start the review/merge process - -.. needextend:: is_external == False and "component_name" in id - :+tags: component_name - -Requirements checklist ----------------------- - -See following requirements inspection checklist for verification of the requirements. - .. toctree:: - :hidden: + requirements chklst_req_inspection diff --git a/score/component_example/docs/requirements/requirements.rst b/score/component_example/docs/requirements/requirements.rst new file mode 100644 index 00000000..4da6914b --- /dev/null +++ b/score/component_example/docs/requirements/requirements.rst @@ -0,0 +1,101 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Component <Name> Requirements +############################# + +.. document:: [Your Component Name] Requirements + :id: doc__mod_temp_component_name_requirements + :status: draft + :safety: ASIL_B + :security: YES + :realizes: wp__requirements_comp + :tags: template + +.. attention:: + The above directive must be updated according to your Component. + + - Modify ``Your Component Name`` to be your Component Name + - Modify ``id`` to be your Component Name in upper snake case preceded by ``doc__`` and followed by ``_requirements`` + - Adjust ``status`` to be ``valid`` + - Adjust ``safety``, ``security`` and ``tags`` according to your needs + +<Headlines (for the list of requirements if structuring is needed)> +=================================================================== + +Functional Requirements +----------------------- + +.. comp_req:: Some Title + :id: comp_req__mod_temp_component_name__some_title + :reqtype: Process + :security: YES + :safety: ASIL_B + :derived_from: feat_req__example_feature__example_req + :status: valid + :satisfied_by: comp__mod_temp_component_name_template + + The Component shall do xyz to another component to bring it to this condition at this time + + Note: (optional, not to be verified) + +.. attention:: + The above directive must be updated according to your component requirements. + + - Replace the example content by the real content for your first requirement + - Set ``derived_from`` with links to Feature requirements + - Set ``satisfied_by`` with a link to the right Component id + - Set ``safety`` and ``security`` to the right value + - Set the status to valid and start the review/merge process + - Add other needed requirements for your component + +Assumption of Use Requirements +------------------------------ + +.. aou_req:: Next Title + :id: aou_req__mod_temp_component_name__next_title + :reqtype: Process + :security: YES + :safety: ASIL_B + :status: valid + + The Component User shall do xyz to use the component safely/securely + +Environmental Requirements +-------------------------- + +.. aou_req:: Another Title + :id: aou_req__mod_temp_component_name__another + :reqtype: Process + :security: YES + :safety: ASIL_B + :status: invalid + :tags: environment + + The Component shall only be used in a xyz environment to ensure its proper functioning. + +Hints +----- + +.. attention:: + The above directives must be updated according to your feature requirements. + + - Replace the example content by the real content for your first requirement (according to :need:`gd_guidl__req_engineering`) + - Set ``safety`` and ``security`` to the right value (ASIL B/QM; YES/NO) + - Set ``reqtype`` with a link to the right value (<Functional|Interface|Process|Non-Functional>) + - Add other needed requirements for your feature + - Set ``status`` to ``valid`` and start the review/merge process + +.. needextend:: is_external == False and "component_name" in id + :+tags: component_name