Source links as Bazel target #358

a-zw · 2026-01-21T16:02:17Z

📌 Description

Provides a Bazel command for source links to make source dependency explicit.
Use this target in docs() instead of implicitly scanning the git repo.
This allows to have source links even for other modules.

🚨 Impact Analysis

This change does not violate any tool requirements and is covered by existing tool requirements
This change does not violate any design decisions
Otherwise I have created a ticket for new tool qualification

✅ Checklist

Added/updated documentation for new or changed features
Added/updated tests to cover the changes
Followed project coding standards and guidelines

github-actions · 2026-01-21T16:03:13Z

License Check Results

🚀 The license check job ran with the Bazel command:

bazel run //src: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: b184dd99-0914-478e-9a62-dd98a9504d60
Computing main repo mapping: 
Computing main repo mapping: 
Loading: 
Loading: 0 packages loaded
Loading: 0 packages loaded
    currently loading: src
Analyzing: target //src:license-check (1 packages loaded, 0 targets configured)
Analyzing: target //src:license-check (1 packages loaded, 0 targets configured)

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

Analyzing: target //src:license-check (129 packages loaded, 2190 targets configured)

Analyzing: target //src:license-check (140 packages loaded, 2700 targets configured)

INFO: Analyzed target //src:license-check (143 packages loaded, 4716 targets configured).
[5 / 12] 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)
INFO: Found 1 target...
Target //src:license.check.license_check up-to-date:
  bazel-bin/src/license.check.license_check
  bazel-bin/src/license.check.license_check.jar
INFO: Elapsed time: 11.789s, Critical Path: 0.51s
INFO: 13 processes: 4 disk cache hit, 9 internal.
INFO: Build completed successfully, 13 total actions
INFO: Running command line: bazel-bin/src/license.check.license_check src/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-01-21T16:09:31Z

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

scripts_bazel/generate_sourcelinks_cli.py

src/extensions/score_draw_uml_funcs/BUILD

scripts_bazel/generate_sourcelinks_cli.py

MaximilianSoerenPollak

Overall looks great from my side.
Script part is simple and concise.

Just had some questions regarding some of the things done as I don't understand them.

src/extensions/score_source_code_linker/__init__.py

MaximilianSoerenPollak

Overall great stuff, thanks for the work.

Just couple comments / questions.

MaximilianSoerenPollak · 2026-01-23T09:53:06Z

docs/how-to/source_to_doc_links.rst

+In you ``BUILD`` files, you specify which source files to scan
+with ``filegroup`` or ``glob`` or whatever Bazel mechanism you prefer.
+Then, you use the ``sourcelinks_json`` rule to scan those files.
+Finally, pass the scan results to the ``docs`` rule as ``sourcelinks`` attribute.


If I remember correctly it was requested that we use non direct language (like you etc.)
Though I don't care too much about it personally.
What's the opinion of the others?

Here is a suggestion how that could look like:

Suggested change

In you ``BUILD`` files, you specify which source files to scan

with ``filegroup`` or ``glob`` or whatever Bazel mechanism you prefer.

Then, you use the ``sourcelinks_json`` rule to scan those files.

Finally, pass the scan results to the ``docs`` rule as ``sourcelinks`` attribute.

In the ``BUILD`` files, it can be specified which source files should be scanned.

This can be achieved with ``filegroup``, ``glob`` or whatever Bazel mechanism is prefered.

Then, the ``sourcelinks_json`` rule is used to scan those files.

Finally, the scanned results need to be passed into ``docs`` rule as ``sourcelinks`` attribute.

src/extensions/score_header_service/BUILD

src/extensions/score_metamodel/BUILD

docs.bzl

scripts_bazel/merge_sourcelinks.py

Currently, we are not using it yet, but this commit adds the Bazel scaffolding to make the json data available.

Fixes consumer checks

AlexanderLanin · 2026-01-23T17:06:27Z

can you make sure the documentation explains that it must be added to all BUILD files and contain ALL files with links, even bazel files or git files or config files or whatever where links can appear. Not just source code.
this will remove source code links from pure sphinx runs and from vs code preview, right?

scripts_bazel/merge_sourcelinks.py

AlexanderLanin · 2026-01-23T17:36:48Z

src/extensions/score_metamodel/BUILD

+    srcs = glob(
+        [
+            "*.py",
+            "*.yaml",


It's super easy to forget some file here. Is a missing source code link safety relevant?

@RolandJentschETAS do you know?

src/extensions/score_metamodel/BUILD

src/extensions/score_source_code_linker/__init__.py

src/BUILD

BUILD

AlexanderLanin · 2026-01-23T17:49:07Z

docs/how-to/source_to_doc_links.rst

+             "@score_process//:needs_json",
+         ],
+         source_dir = "docs",
+         sourcelinks = [":my_source_links"],


up to now docs() is defining internal targets like needs_json itself. All in one command. Can we do the same with sourcelinks_json?

Isn't this the solution we had wayyy back when we first introduced scl? :D Oh the cyclical nature of things.

scripts_bazel/tests/BUILD

scripts_bazel/tests/generate_sourcelinks_cli_test.py

scripts_bazel/merge_sourcelinks.py

src/extensions/score_source_code_linker/BUILD

MaximilianSoerenPollak · 2026-01-26T15:11:54Z

src/extensions/score_source_code_linker/needlinks.py



 def load_source_code_links_json(file: Path) -> list[NeedLink]:
+    if not file.is_absolute():


Is this following symlinks?
Though not sure if it matters.

I assume it does because Bazel is using symlinks everywhere.

src/extensions/score_sphinx_bundle/BUILD

scripts_bazel/tests/generate_sourcelinks_cli_test.py

MaximilianSoerenPollak · 2026-01-27T12:38:32Z

docs/concepts/docs_deps.rst

+Docs Dependencies
+==========================
+
+When running ``bazel run :docs``, the documentation build system orchestrates multiple interconnected dependencies to produce HTML documentation.


Can be fixed in future PR:

isn't it bazel run //:docs

otherwise you might not get the right target.

docs/concepts/docs_deps.rst

scripts_bazel/tests/generate_sourcelinks_cli_test.py

Co-authored-by: Maximilian Sören Pollak <maximilian.pollak@qorix.com> Signed-off-by: Andreas Zwinkau <95761648+a-zw@users.noreply.github.com>

MaximilianSoerenPollak

Thanks for this work. Truly appreciated.

AlexanderLanin · 2026-01-27T14:57:35Z

I'd like to discuss the user facing API. As needs_json is hidden within docs() but this new target is not.

MaximilianSoerenPollak · 2026-01-27T15:00:14Z

I'd like to discuss the user facing API. As needs_json is hidden within docs() but this new target is not.

We for sure have to do this.
A unified user facing interface that is simple to use & understand is for sure needed.

I think that we could introduce with the further functionality that is I think still missing here?

github-project-automation bot added this to Infrastructure Jan 21, 2026

github-project-automation bot moved this to Draft in Infrastructure Jan 21, 2026

a-zw mentioned this pull request Jan 21, 2026

[Discussion] Solutions & Approaches to Reference Integration 'source code linker' not working #357

Closed

MaximilianSoerenPollak reviewed Jan 22, 2026

View reviewed changes

scripts_bazel/generate_sourcelinks_cli.py Show resolved Hide resolved

MaximilianSoerenPollak reviewed Jan 22, 2026

View reviewed changes

scripts_bazel/generate_sourcelinks_cli.py Outdated Show resolved Hide resolved

MaximilianSoerenPollak reviewed Jan 22, 2026

View reviewed changes

src/extensions/score_draw_uml_funcs/BUILD Show resolved Hide resolved

MaximilianSoerenPollak reviewed Jan 22, 2026

View reviewed changes

scripts_bazel/generate_sourcelinks_cli.py Show resolved Hide resolved

MaximilianSoerenPollak reviewed Jan 22, 2026

View reviewed changes

a-zw commented Jan 22, 2026

View reviewed changes

src/extensions/score_source_code_linker/__init__.py Show resolved Hide resolved

a-zw changed the title ~~Provide //:sourcelinks_json~~ Source links as Bazel target Jan 22, 2026

a-zw force-pushed the sourcelinks_json branch 2 times, most recently from d781b67 to 529deb8 Compare January 22, 2026 16:12

a-zw marked this pull request as ready for review January 22, 2026 16:40

a-zw requested review from AlexanderLanin, dcalavrezo-qorix and nradakovic as code owners January 22, 2026 16:40

MaximilianSoerenPollak reviewed Jan 23, 2026

View reviewed changes

a-zw force-pushed the sourcelinks_json branch from 71b7a05 to cbb7a3f Compare January 23, 2026 14:49

a-zw added 9 commits January 23, 2026 17:27

Provide //:sourcelinks_json

f6991e9

Funnel sourcelinks into Sphinx extension

61dad86

Currently, we are not using it yet, but this commit adds the Bazel scaffolding to make the json data available.

Read source links json when available

d31a8fc

Fix CI checks

ac852e5

Fix tests

69991f3

Document sourcelinks_json how to

740c4e2

Fix linter warnings

c4d8950

Test the new scripts

2842afb

Explicit module

502f550

Fixes consumer checks

a-zw force-pushed the sourcelinks_json branch from 8eae746 to 502f550 Compare January 23, 2026 16:27

AlexanderLanin reviewed Jan 23, 2026

View reviewed changes

scripts_bazel/merge_sourcelinks.py Show resolved Hide resolved

AlexanderLanin reviewed Jan 23, 2026

View reviewed changes