add documentation examples by RolandJentschETAS · Pull Request #58 · eclipse-score/module_template

RolandJentschETAS · 2026-04-01T09:34:45Z

Move the documentation examples from process documentation to module template.

See belonging PR eclipse-score/process_description#632 in process.

github-actions · 2026-04-01T09:38:30Z

License Check Results

🚀 The license check job ran with the Bazel command:

bazel run --lockfile_mode=error //:license-check

Status: ⚠️ Needs Review

Click to expand output

[License Check Output]
Extracting Bazel installation...
Starting local Bazel server (8.3.0) and connecting to it...
INFO: Invocation ID: 372bf7f1-ccc0-4eeb-a045-0ff96a7f1f4c
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Loading: 
Loading: 0 packages loaded
Loading: 0 packages loaded
Loading: 0 packages loaded
    currently loading: 
Loading: 0 packages loaded
    currently loading: 
Loading: 0 packages loaded
    currently loading: 
Loading: 0 packages loaded
    currently loading: 
Analyzing: target //:license-check (1 packages loaded, 0 targets configured)
Analyzing: target //:license-check (1 packages loaded, 0 targets configured)

Analyzing: target //:license-check (27 packages loaded, 9 targets configured)

Analyzing: target //:license-check (81 packages loaded, 9 targets configured)

Analyzing: target //:license-check (90 packages loaded, 9 targets configured)

Analyzing: target //:license-check (133 packages loaded, 1517 targets configured)

Analyzing: target //:license-check (154 packages loaded, 4815 targets configured)

Analyzing: target //:license-check (158 packages loaded, 7650 targets configured)

Analyzing: target //:license-check (161 packages loaded, 7660 targets configured)

Analyzing: target //:license-check (161 packages loaded, 7660 targets configured)

Analyzing: target //:license-check (161 packages loaded, 7660 targets configured)

Analyzing: target //:license-check (164 packages loaded, 9544 targets configured)

Analyzing: target //:license-check (164 packages loaded, 9545 targets configured)

Analyzing: target //:license-check (164 packages loaded, 9545 targets configured)

Analyzing: target //:license-check (165 packages loaded, 9669 targets configured)

Analyzing: target //:license-check (166 packages loaded, 9789 targets configured)

Analyzing: target //:license-check (166 packages loaded, 9789 targets configured)

INFO: Analyzed target //:license-check (167 packages loaded, 11724 targets configured).
[9 / 16] Creating runfiles tree bazel-out/k8-opt-exec-ST-d57f47055a04/bin/external/score_tooling+/dash/tool/formatters/dash_format_converter.runfiles [for tool]; 0s local ... (2 actions, 1 running)
[12 / 16] JavaToolchainCompileClasses external/rules_java+/toolchains/platformclasspath_classes; 1s disk-cache, processwrapper-sandbox ... (2 actions running)
INFO: From Generating Dash formatted dependency file ...:
INFO: Successfully converted 2 packages from Cargo.lock to bazel-out/k8-fastbuild/bin/formatted.txt
[14 / 16] JavaToolchainCompileBootClasspath external/rules_java+/toolchains/platformclasspath.jar; 0s disk-cache, processwrapper-sandbox
INFO: Found 1 target...
Target //:license.check.license_check up-to-date:
  bazel-bin/license.check.license_check
  bazel-bin/license.check.license_check.jar
INFO: Elapsed time: 205.352s, Critical Path: 2.90s
INFO: 16 processes: 12 internal, 3 processwrapper-sandbox, 1 worker.
INFO: Build completed successfully, 16 total actions
INFO: Running command line: bazel-bin/license.check.license_check ./formatted.txt <args omitted>
usage: org.eclipse.dash.licenses.cli.Main [-batch <int>] [-cd <url>]
       [-confidence <int>] [-ef <url>] [-excludeSources <sources>] [-help] [-lic
       <url>] [-project <shortname>] [-repo <url>] [-review] [-summary <file>]
       [-timeout <seconds>] [-token <token>]

github-actions · 2026-04-01T09:39:22Z

The created documentation from the pull request is available at: docu-html

This reverts commit 683d5df.

MaximilianSoerenPollak · 2026-04-01T11:46:49Z

score/example_component/docs/detailed_design/detailed_design_example.rst

We aren't using doxygen, is this a typo / old copy paste error?

The description itself is directly moved from process description. Maybe the process description was wrong.

MaximilianSoerenPollak · 2026-04-01T11:48:30Z

docs/score/example_component/component_architecture_template.rst

+   # SPDX-License-Identifier: Apache-2.0
+   # *******************************************************************************
+
+.. include:: ../../../score/example_component/docs/component_architecture_template.rst


I don't understand this, can you explain?
Why is this included and not just in one place?

According to the documentation guidelines the component documentation is located nearby the components. That means in the docs folder of the component. If I want to refer to that from the architecture I have to link it in this way.

Not sure how to solve different parts in one repo in an other way. Maybe by an index.rst at top level.

There currently isn't a way to have different TOP LEVEL doc folders. They all have to be in a single combined folder.

Or (as is shown here) it is linked in this way. I really prefer to have the documentation directly in the near of the sourcecode. Otherwise (this is really my experience from any previous project) it will not be maintained by the developers, because it is out of their local focus.

That is an issue of the maintainers / codeowners of the repo. They have to define that behaviour and how it is handled in repo. In my opinion it makes the most sense to have them enforce the documentation is kept up to date otherwise the feature should not be merged. Though unsure. @AlexanderLanin @masc2023 do we know if there is any written record of this somewhere ? I couldn''t find it in my search.

You mean about "There currently isn't a way to have different TOP LEVEL doc folders. They all have to be in a single combined folder."
I am not aware about any DR about that topic

isnt that what any_folder is for?

Any folder was reverted in the newest docs-as-code release, as it broke ref-integration if used and was fundamentally not fixable in a reasonable amount of time with the chosen approach

What is the meaning of "any_folder" ?

Additionally I'm not sure if there is any issue. There is the possibility with the include. Or via an additional path. See https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-include_patterns

Changed to main index.rst in main folder with include path.

MaximilianSoerenPollak · 2026-04-01T11:49:07Z

README.md

+| `score/`                            | Source files and Unit Tests for the module        |
 | `tests/`                            | Component and Feature Integration Tests (CIT&FIT) |
 | `examples/`                         | Example files used for guidance                   |
 | `docs/`                             | Documentation (Doxygen for C++ / mdBook for Rust) |


As far as I know doxygen is not used currently.
OR am I on old information?

This is unchanged (was there also before PR). We have to check that.

Implementation process is not finalised yet, that was planned for implementation, detailed design

arsibo · 2026-04-02T10:28:28Z

After discussion with Roland and the discussion in the process meeting (02.04.2026)
We will prepare a DR. We discussed the point in January , but haven't finalized it yet (#40)

In case that the new DR can not be decided in the next two weeks, we need a workaround step for that PR.
Maybe we can do it as intermediate solution.

aschemmel-tech · 2026-04-02T11:38:38Z

The folder structure already documented in https://eclipse-score.github.io/score/main/contribute/general/folder.html#module-folder-structure does not have the problem as I understand (the entry point for sphinx would be <module_name> folder). Why not use this? But I understand that we would not like to have a path which is like https://github.com/eclipse-score/<repository_name>/<module_name> because these may be the same, but please consider that we defined "This Delivery Container can contain one or more Dependable Elements" in https://eclipse-score.github.io/process_description/main/general_concepts/score_building_blocks_concept.html so a reposity could contain more than one module.

aschemmel-tech

see inline comments

docs/stakeholder_requirements_template.rst

aschemmel-tech · 2026-04-09T09:17:23Z

docs/aou_requirements_template.rst

Duplicated AoUs from component and feature sections. Why?

aschemmel-tech · 2026-04-09T09:29:34Z

docs/architecture/architecture_modeling_example.rst

Please rename the folder this resides in to "architecture_example" or "example" as also the feature architecture templates will come here and should be in a folder called "architecture"

aschemmel-tech · 2026-04-09T09:32:10Z

docs/verification_report/index.rst

Also here, rather call the folder and headline "verification" as the feature integration test templates may also move here.

add documentation examples

a4b9193

github-project-automation bot added this to INF - Infrastructure Community Apr 1, 2026

github-project-automation bot moved this to Backlog in INF - Infrastructure Community Apr 1, 2026

RolandJentschETAS added 5 commits April 1, 2026 11:46

fix copyright check

d663e72

add copyright

bf89f92

add newline at end of file

683d5df

Revert "add newline at end of file"

c23e2f9

This reverts commit 683d5df.

add newlines

87736d6

MaximilianSoerenPollak reviewed Apr 1, 2026

View reviewed changes

RolandJentschETAS mentioned this pull request Apr 2, 2026

Start to move examples to template module repository eclipse-score/process_description#632

Merged

RolandJentschETAS mentioned this pull request Apr 2, 2026

Implement DR-007 eclipse-score/docs-as-code#392

Open

RolandJentschETAS mentioned this pull request Apr 2, 2026

EPIC: Metamodel Usability Adaptions eclipse-score/process_description#450

Open

2 tasks

RolandJentschETAS added 7 commits April 7, 2026 13:50

take over general structure according to process

dd338b2

use folder template from process repo

a368dd9

fix commit hash

ef83c1f

fix strange format error

90b3293

structuring module documentation

3e7930d

add directory tree picture

932dd61

add some comments

32f0836

aschemmel-tech requested changes Apr 9, 2026

View reviewed changes

RolandJentschETAS added 4 commits April 9, 2026 11:45

change to include folder approach

66f9fae

use main path instead of link

f00943c

fix builds

e781916

remove stakeholder reqs

60aa73e

remove stakeholder reqs

c14608e

Conversation

RolandJentschETAS commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

License Check Results

Uh oh!

github-actions bot commented Apr 1, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RolandJentschETAS Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RolandJentschETAS Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

arsibo commented Apr 2, 2026

Uh oh!

aschemmel-tech commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aschemmel-tech left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

RolandJentschETAS commented Apr 1, 2026 •

edited

Loading

github-actions bot commented Apr 1, 2026 •

edited

Loading

RolandJentschETAS Apr 2, 2026 •

edited

Loading

RolandJentschETAS Apr 1, 2026 •

edited

Loading

aschemmel-tech commented Apr 2, 2026 •

edited

Loading