Add Documentation for Source Code Linker by MaximilianSoerenPollak · Pull Request #2461 · eclipse-score/score

MaximilianSoerenPollak · 2026-01-19T16:35:54Z

This will add additional documentation for developers about the Source Code Linker and it's capabilities.

github-actions · 2026-01-19T16:36:07Z

⚠️ Docs-as-Code version mismatch detected
Please check the CI build logs for details and align the documentation version with the Bazel dependency.

pawelrutkaq · 2026-01-20T07:14:32Z

@@ -0,0 +1,125 @@
+.. 


I would just call it code tracability tooling as geenral tools means nothing.

github-actions · 2026-01-20T07:49:28Z

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

pawelrutkaq · 2026-01-20T08:18:14Z

+      """Your function that implements the requirement partiall or fully"""
+      ...
+
+The parser will look through most files but not those that fulfil any of these properties


hard to understand sentence

Re-wrote it.

pawelrutkaq · 2026-01-20T08:20:19Z

+The implementation here differs based on your source code language though.
+So it is best if you read up in the language you want to develop in how to do this.
+
+In rough terms the data flow looks as follows.


In rough terms the data flow looks as follows:

pawelrutkaq · 2026-01-20T08:21:13Z

+
+You can now also do statistics on your tests. `Docs as Code Test Statistics examples <https://eclipse-score.github.io/docs-as-code/main/internals/requirements/test_overview.html>`_
+
+


I think this needs betetr explanation and not just "in cloud" one. @PiotrKorkus maybe some comments ?

Is this comment on the wrong line? I can't quiet follow you here.

agree, maybe you can provide codeblock with ..needtable & ..needpie examples? Button edit on github still doesn't work, so it can be difficult to others to quickly find the code.
Also I would appreciate information if cross-repo linking and reporting is possible

pawelrutkaq · 2026-01-20T08:21:40Z

+`Python implementation [NOT LINKED YET]`
+`RUST Implementation [NOT LINKED YET]`
+`CPP Implementation [NOT LINKED YET]`
+


Do we need this ? Isn;t this enought to just link to doc-as-code and thats it ?

How you do the testing properties in each is different, so we most likely should describe that quickly with an example?
As in 'docs-as-code' only the python one is described (if even)

pawelrutkaq · 2026-01-20T08:22:29Z

+Traceability Tooling
+####################
+
+This document describes tools or some functionality of them, that can be used regardless of source code language.These tools are also provided by S-CORE projects, like Docs-As-Code.


"This document describes tools or some functionality of them" The whole description in this doc shall be precise imho as this is what will be used.

PiotrKorkus · 2026-01-20T08:26:17Z

+Link Requirements to Tests
+**************************
+
+There is a tool that has the ability to link requirements to your tests as well as provide virtual tests needs in order to make statistics etc. possible to be rendered.


Add link to tool

This sentence is a bit weird :D, I re-word it and add the link to the tool.

PiotrKorkus · 2026-01-20T08:27:35Z

+In rough terms the data flow looks as follows.
+
+Your testing framework produces XML files with pre-defined properties.
+These XML files get read in and parsed. The test needs get build from the parsed data and linked to the requirements mentioned.


These XML files are loaded and parsed. The test needs to get build details from the parsed data and link it to the requirements mentioned. ?

This sounds nicer. Will adopt this wording.

PiotrKorkus · 2026-01-20T08:36:44Z

+
+You can now also do statistics on your tests. `Docs as Code Test Statistics examples <https://eclipse-score.github.io/docs-as-code/main/internals/requirements/test_overview.html>`_
+
+


agree, maybe you can provide codeblock with ..needtable & ..needpie examples? Button edit on github still doesn't work, so it can be difficult to others to quickly find the code.
Also I would appreciate information if cross-repo linking and reporting is possible

PiotrKorkus · 2026-01-20T08:38:55Z

+      """Your function that implements the requirement partiall or fully"""
+      ...
+
+An rendered example of a need where this is implemented can be seen in `Rendered Example <https://eclipse-score.github.io/docs-as-code/main/internals/requirements/requirements.html#tool_req__docs_common_attr_id>`_


A rendered example

Incooperating PR comments Adding screenshot of rendered example instead of linking to it

AlexanderLanin · 2026-01-23T09:29:38Z

+It is either `# req-Id: <your requirement>` or `# req-traceability: <your requirement>`
+If there is multiple requirements that need to be linked to this place in the source code, repeat the line for each one.
+
+As an example for one requirement:


Does this extend or replace this docu?
https://eclipse-score.github.io/docs-as-code/main/how-to/source_to_doc_links.html

I feel all docs-as-code howto should be at docs-as-code, and this should only link there?

Extend. It's suppose to make the 'score contribution / development' place a one stop shop to at least start and get all important information.

I agree that this makes it a bit cumbersome if we change things, as we have to change it in two places. Though I found just adding a link with a single sentence like 'please find the documentation for traceability here' also a bit too small.

Theoretically we could do that too. Just have a link to the how to into docs as code and extend the how to inside docs as code to make it more cohesive.
If that works better, I can change it to that.

@AlexanderLanin definitely from dev perspective, all those fundamental things without details, and tones of other doc are needed in one place. Most of people need only know how pattern shall look like and thats it. This is valuable here.

@pawelrutkaq @MaximilianSoerenPollak we need that link, as we have to expect that this howto will be out of date and not updated at some point. I'm 100% sure, we'll forget to update it here on every important change. So overview here + link to up-to-date-and-more-detailed-instructions seems good?!

That currently is there no?
The last section has a 'Further information' with a link to the current Docs-AS-Code documentation.

Or do you think it should be more visible or at a different spot?

PiotrKorkus

please fix one link

* Add Documentation for Docs-as-Code tools

MaximilianSoerenPollak added 2 commits January 19, 2026 15:03

Add Documentation for Docs-as-Code tools

5749170

Adding needed context to requirement

26e0844

pawelrutkaq reviewed Jan 20, 2026

View reviewed changes

Fixing the requirement & renaming files

f083b7d

pawelrutkaq requested changes Jan 20, 2026

View reviewed changes

PiotrKorkus reviewed Jan 20, 2026

View reviewed changes

MaximilianSoerenPollak added 3 commits January 20, 2026 10:24

Updating documentation

11bbda3

Incooperating PR comments Adding screenshot of rendered example instead of linking to it

Added links to python testing examples

8f2842b

Fix link naming

5c3c087

MaximilianSoerenPollak marked this pull request as ready for review January 22, 2026 13:47

MaximilianSoerenPollak requested a review from a team as a code owner January 22, 2026 13:47

MaximilianSoerenPollak requested review from PiotrKorkus and pawelrutkaq January 22, 2026 13:47

FScholPer previously approved these changes Jan 23, 2026

View reviewed changes

AlexanderLanin reviewed Jan 23, 2026

View reviewed changes

pawelrutkaq previously approved these changes Jan 26, 2026

View reviewed changes

PiotrKorkus requested changes Jan 26, 2026

View reviewed changes

Comment thread docs/contribute/development/traceability_tooling.rst Outdated

Update Link to working one

7af0488

MaximilianSoerenPollak dismissed stale reviews from pawelrutkaq and FScholPer via 7af0488 January 26, 2026 08:51

MaximilianSoerenPollak requested review from AlexanderLanin, PiotrKorkus and pawelrutkaq January 26, 2026 08:57

PiotrKorkus approved these changes Jan 26, 2026

View reviewed changes

MaximilianSoerenPollak merged commit a42c6cc into eclipse-score:main Jan 26, 2026
6 checks passed

masc2023 pushed a commit that referenced this pull request Feb 8, 2026

Add Documentation for Source Code Linker (#2461)

71a4cb3

* Add Documentation for Docs-as-Code tools


		You can now also do statistics on your tests. `Docs as Code Test Statistics examples <https://eclipse-score.github.io/docs-as-code/main/internals/requirements/test_overview.html>`_

Conversation

MaximilianSoerenPollak commented Jan 19, 2026

Uh oh!

github-actions Bot commented Jan 19, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jan 20, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

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!

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!

Choose a reason for hiding this comment

Uh oh!

AlexanderLanin Jan 26, 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!

PiotrKorkus left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

AlexanderLanin Jan 26, 2026 •

edited

Loading