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: 7d2dfee6-17fb-407c-afd8-0ca506b708f7
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Loading: 
Loading: 0 packages loaded
Loading: 0 packages loaded
    currently loading: src
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 (70 packages loaded, 9 targets configured)

Analyzing: target //src:license-check (119 packages loaded, 806 targets configured)

Analyzing: target //src:license-check (135 packages loaded, 2651 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).
[10 / 13] JavaToolchainCompileBootClasspath external/rules_java+/toolchains/platformclasspath.jar; 0s disk-cache
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: 15.244s, Critical Path: 0.41s
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

MaximilianSoerenPollak · 2026-01-22T08:07:37Z

scripts/generate_sourcelinks_cli.py

+import sys
+from pathlib import Path
+
+from src.extensions.score_source_code_linker.generate_source_code_links_json import (


Might need to either make this function public or make a public counterpart.

I'm not sure yet. Eventually, we should be able to extract it from the Sphinx extension, because the extension shall only consume the json files.

scripts/generate_sourcelinks_cli.py

src/extensions/score_draw_uml_funcs/BUILD

scripts/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/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?

AlexanderLanin · 2026-01-23T17:16:40Z

scripts/merge_sourcelinks.py

+# *******************************************************************************
+
+"""
+Merge multiple sourcelinks JSON files into a single JSON file.


The scripts directory is only for local development (linters; super confusing) so far.

This is the bazel side of src/extensions/score_source_code_linker? I would still put it to src/extensions/score_source_code_linker/bazel_prebuild_step?

Can you please add README.md files to any new directory explaining what that is and a rough sketch of the architecture?

AlexanderLanin · 2026-01-23T17:26:41Z

scripts/merge_sourcelinks.py

+# *******************************************************************************
+
+"""
+Merge multiple sourcelinks JSON files into a single JSON file.


Can you please add README.md files to any new directory explaining what that is and a rough sketch of the architecture?

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

scripts/merge_sourcelinks.py

+
+    merged = []
+    for json_file in args.files:
+        if json_file.exists():


no warning on not exists?

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

scripts/merge_sourcelinks.py

+        if json_file.exists():
+            with open(json_file) as f:
+                data = json.load(f)
+                if isinstance(data, list):


no warning on else?

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?

AlexanderLanin · 2026-01-23T17:38:28Z

src/extensions/score_metamodel/BUILD

            "tests/**/*.rst",
            "tests/**/*.yaml",
-        ],
+        ] + ["tests/rst/conf.py"],


Suggested change

] + ["tests/rst/conf.py"],

"tests/rst/conf.py"],

Why do we need to add this file now?

AlexanderLanin · 2026-01-23T17:41:10Z

src/extensions/score_source_code_linker/__init__.py

-        get_cache_filename(outdir, "score_source_code_linker_cache.json")
-    )
+    source_code_links_json = os.environ.get("SCORE_SOURCELINKS")
+    if not source_code_links_json:


Can you explain this if? Maybe in some overarching concept? Maybe in a separate PR ;-)

AlexanderLanin · 2026-01-23T17:46:10Z

src/BUILD

+        "//src/extensions/score_sphinx_bundle:all_sources",
+        "//src/extensions/score_sync_toml:all_sources",
+        "//src/find_runfiles:all_sources",
+        "//src/helper_lib:all_sources",


No clever collection mechanism in bazel? This looks extremely error prone.

AlexanderLanin · 2026-01-23T17:47:03Z

BUILD

+sourcelinks_json(
+    name = "sourcelinks_json",
+    srcs = [
+        "//src:all_sources",


all following items are already included in src:all_sources?

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?

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/generate_sourcelinks_cli.py 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/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

Source links as Bazel target #358

Are you sure you want to change the base?

Source links as Bazel target #358

Conversation

a-zw commented Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📌 Description

🚨 Impact Analysis

✅ Checklist

Uh oh!

github-actions bot commented Jan 21, 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 Jan 21, 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!

Uh oh!

MaximilianSoerenPollak left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

MaximilianSoerenPollak left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AlexanderLanin commented Jan 23, 2026

Uh oh!

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

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

a-zw commented Jan 21, 2026 •

edited

Loading

github-actions bot commented Jan 21, 2026 •

edited

Loading

AlexanderLanin Jan 23, 2026 •

edited

Loading