Skip to content

Commit 7b97732

Browse files
RolandJentschETASRolandJentschETAS
authored
change document structure and unhidden documents (#78)
1 parent 61d0c81 commit 7b97732

6 files changed

Lines changed: 71 additions & 145 deletions

File tree

‎index.rst‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -108,8 +108,13 @@ Component documentation
108108
:maxdepth: 1
109109

110110
score/component_example/docs/index
111-
score/component_example/docs/architecture/component_architecture_template
112-
score/component_example/docs/detailed_design/detailed_design_example
111+
score/component_example/docs/architecture/index
112+
score/component_example/docs/detailed_design/index
113+
score/component_example/docs/requirements/index
114+
score/component_example/docs/safety_analysis/dfa
115+
score/component_example/docs/safety_analysis/fmea
116+
score/component_example/docs/safety_analysis/aou_requirements_template
117+
score/component_example/docs/component_classification
113118

114119
Examples
115120
--------

‎score/component_example/docs/architecture/index.rst‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -141,3 +141,22 @@ Internal Components
141141

142142
- Replace the example content by the real content (according to :need:`gd_guidl__arch_design`)
143143
- Set the status to valid and start the review/merge process
144+
145+
Component Architecture Template
146+
-------------------------------
147+
148+
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.
149+
150+
.. toctree::
151+
152+
component_architecture_template
153+
154+
155+
Architecture Checklist
156+
----------------------
157+
158+
See following architecture inspection checklist for verification of the architecture.
159+
160+
.. toctree::
161+
162+
chklst_arc_inspection

‎score/component_example/docs/detailed_design/detailed_design_example.rst‎

Lines changed: 6 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -25,53 +25,18 @@ Description
2525
Static Diagrams for Unit Interactions
2626
-------------------------------------
2727

28-
.. dd_sta:: dd example static
29-
:id: dd_sta__example_feature__approver
30-
:security: NO
31-
:safety: ASIL_B
32-
:status: valid
33-
:implements: comp_req__example_feature__example_req
34-
:satisfies: comp_arc_sta__mod_temp_component_name__sv
35-
3628
.. uml:: dd_example_ex_sta.puml
3729

38-
Dynamic Diagrams for Unit Interactions
39-
--------------------------------------
40-
41-
.. dd_dyn:: dd example dynamic
42-
:id: dd_dyn__example_feature__dynamic
43-
:security: NO
44-
:safety: ASIL_B
45-
:status: valid
46-
:implements: comp_req__example_feature__example_req
47-
:satisfies: comp_arc_sta__mod_temp_component_name__sv
30+
Dynamic Diagrams for Unit Interactions (optional)
31+
--------------------------------------------------
4832

4933
.. uml:: dd_example_ex_dyn.puml
5034

5135
Units within the Component
5236
--------------------------
53-
From here onwards the needs are defined in the source code and will be automatically generated and linked via doxygen.
54-
55-
SW Unit
56-
*******
57-
58-
The unit description is generated from the source code and linked with
59-
the need ID sw_unit__example_feature__unit1.
60-
61-
Interface
62-
*********
63-
64-
The interface description is generated from the source code and linked with
65-
the need ID sw_unit_int__example_feature__u1_i1.
66-
67-
SW Unit
68-
*******
69-
70-
The unit description is generated from the source code and linked with
71-
the need ID sw_unit__example_feature__unit2.
7237

73-
Interface
74-
*********
38+
The units are defined in the source code. The relationship between a unit and the
39+
component is established implicitly through the file path.
7540

76-
The interface description is generated from the source code and linked with
77-
the need ID sw_unit_int__example_feature__u2_i2.
41+
- unit1: implements the main logic (see source code for details)
42+
- unit2: injected into unit1 via dependency injection for testability

‎score/component_example/docs/detailed_design/index.rst‎

Lines changed: 29 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -52,107 +52,48 @@ Rationale Behind Decomposition into Units
5252

5353
Static Diagrams for Unit Interactions
5454
-------------------------------------
55-
.. code-block:: rst
56-
57-
.. dd_sta:: <Title>
58-
:id: dd_sta__<Component>__<Title>
59-
:security: <YES|NO>
60-
:safety: <QM|ASIL_B>
61-
:status: <valid|invalid>
62-
:implements: <link to component requirement id>
63-
:satisfies: <link to component architecture id>
64-
:belongs_to: <link to component id>
65-
:includes: <link to sw_unit id>, <link to sw_unit interface id>
66-
67-
.. needarch:: or .. image:: <link to drawio image>
68-
69-
Dynamic Diagrams for Unit Interactions
70-
--------------------------------------
71-
.. code-block:: rst
72-
73-
.. dd_dyn:: <Title>
74-
:id: dd_dyn__<Component>__<Title>
75-
:security: <YES|NO>
76-
:safety: <QM|ASIL_B>
77-
:status: <valid|invalid>
78-
:implements: <link to component requirement id>
79-
:satisfies: <link to component architecture id>
80-
:belongs_to: <link to component id>
81-
:includes: <link to sw_unit id>, <link to sw_unit interface id>
82-
83-
.. needarch:: or .. image:: <link to drawio image>
8455

85-
Units within the Component
86-
--------------------------
87-
88-
In your rst file:
89-
90-
.. code-block:: rst
91-
92-
.. sw_unit:: cpp unit
93-
:id: sw_unit__<Component>__<title>
94-
:belongs_to: <link to component id>
95-
96-
This implements the ....
56+
A static view provides an overview of the units and their relationships using
57+
UML 2.0 notations (e.g. class diagrams, component diagrams). Use ``.. uml::``
58+
or ``.. image::`` directives to include the diagram.
9759

98-
In your source file, any programming language, here with C++:
60+
Dynamic Diagrams for Unit Interactions (optional)
61+
--------------------------------------------------
9962

100-
.. code-block:: cpp
63+
A dynamic view illustrates how the units within a component interact over their
64+
interfaces to fulfill a specific use case or functionality. It is optional when the
65+
component's behaviour is straightforward and can be understood from the static view
66+
and interface documentation alone.
10167

102-
# need-Id: sw_unit__<Component>__<title>
103-
class <class name> {
104-
public:
68+
Use standard UML behavioural diagrams (sequence diagrams, state machine diagrams)
69+
with ``.. uml::`` or ``.. image::`` directives.
10570

106-
};
107-
108-
Interface View
109-
--------------
110-
111-
In your rst file:
112-
113-
.. code-block:: rst
71+
Units within the Component
72+
--------------------------
11473

115-
.. sw_unit_int:: <here InterfaceDemo - change it>
116-
:id: sw_unit_int__<Component>__<title>
117-
:belongs_to: <link to sw_unit id>
118-
:implements: <real_arc_int, real_arc_int_op>
74+
The relationship between a unit and its parent component is established implicitly
75+
through the file path. Each component has its own directory, and units residing
76+
within that directory belong to it. The unit's attributes and behaviour are documented
77+
in the source code itself. A separate static diagram per unit is not required.
11978

120-
This implements the ....
79+
Interface documentation of a software unit is part of the source code (e.g. public
80+
API headers, trait definitions, or documented function signatures).
12181

122-
In your source file, any programming language, here with C++:
82+
Inspection Checklist
83+
--------------------
12384

124-
.. code-block:: cpp
85+
The checklist for verification of the detailed design inspection can be found here:
12586

126-
# need-Id: sw_unit__<Component>__<title>
127-
class InterfaceDemo
128-
{
129-
public:
130-
virtual ~InterfaceDemo() {}
131-
virtual void OverrideMe() = 0;
132-
};
87+
.. toctree::
13388

134-
- For cpp using doxygen comments
89+
chklst_impl_inspection
13590

136-
.. code-block:: cpp
13791

138-
/**
139-
* @rst
140-
* .. sw_unit_int:: cpp unit
141-
* :id: sw_unit_int__<Component>__<title>
142-
* :belongs_to: <link to sw_unit id>
143-
* :implements: <real_arc_int, real_arc_int_op>
144-
*
145-
* This implements the ....
146-
* @endrst
147-
*/
92+
Detail design example
93+
---------------------
14894

149-
- For rust
95+
An example of documenting detailed design can be found in:
15096

151-
.. code-block:: rust
97+
.. toctree::
15298

153-
//! .. sw_unit_int:: rust unit
154-
//! :id: sw_unit_int__<Component>__<title>
155-
//! :belongs_to: <link to sw_unit id>
156-
//! :implements: <real_arc_int, real_arc_int_op>
157-
//!
158-
//! This implements the ....
99+
detailed_design_example

‎score/component_example/docs/index.rst‎

Lines changed: 0 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -149,17 +149,3 @@ Footnotes
149149
=========
150150

151151
[A collection of footnotes cited in the CR, and a place to list non-inline hyperlink targets.]
152-
153-
.. toctree::
154-
:hidden:
155-
156-
architecture/index.rst
157-
architecture/chklst_arc_inspection.rst
158-
component_classification.rst
159-
detailed_design/index.rst
160-
detailed_design/chklst_impl_inspection.rst
161-
requirements/index.rst
162-
requirements/chklst_req_inspection.rst
163-
safety_analysis/fmea.rst
164-
safety_analysis/dfa.rst
165-
safety_analysis/aou_requirements_template.rst

‎score/component_example/docs/requirements/index.rst‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,3 +99,13 @@ Hints
9999

100100
.. needextend:: "component_name" in id
101101
:+tags: component_name
102+
103+
Requirements checklist
104+
----------------------
105+
106+
See following requirements inspection checklist for verification of the requirements.
107+
108+
.. toctree::
109+
:hidden:
110+
111+
chklst_req_inspection

0 commit comments

Comments
 (0)