Source links as Bazel target

BUILD

@@ -11,9 +11,8 @@
 # SPDX-License-Identifier: Apache-2.0
 # *******************************************************************************
 
-load("@aspect_rules_py//py:defs.bzl", "py_library")
 load("@score_tooling//:defs.bzl", "cli_helper", "copyright_checker")
-load("//:docs.bzl", "docs")
+load("//:docs.bzl", "docs", "sourcelinks_json")
 
 package(default_visibility = ["//visibility:public"])
 
@@ -29,11 +28,21 @@ copyright_checker(
     visibility = ["//visibility:public"],
 )
 
+sourcelinks_json(
+    name = "sourcelinks_json",
+    srcs = [
+        "//scripts_bazel:sources",
+        "//src:all_sources",
+    ],
+    visibility = ["//visibility:public"],
+)
+
 docs(
     data = [
         "@score_process//:needs_json",
     ],
     source_dir = "docs",
+    sourcelinks = [":sourcelinks_json"],
 )
 
 cli_helper(

MODULE.bazel

@@ -104,7 +104,7 @@ bazel_dep(name = "score_process", version = "1.4.2")
 
 # Add Linter
 bazel_dep(name = "rules_multitool", version = "1.9.0")
-bazel_dep(name = "score_tooling", version = "1.0.2")
+bazel_dep(name = "score_tooling", version = "1.0.5")
 
 multitool_root = use_extension("@rules_multitool//multitool:extension.bzl", "multitool")
 use_repo(multitool_root, "actionlint_hub", "multitool", "ruff_hub", "shellcheck_hub", "yamlfmt_hub")

docs.bzl

@@ -56,12 +56,40 @@ def _rewrite_needs_json_to_docs_sources(labels):
             out.append(s)
     return out
 
-def docs(source_dir = "docs", data = [], deps = []):
+def _merge_sourcelinks(name, sourcelinks):
+    """Merge multiple sourcelinks JSON files into a single file.
+
+    Args:
+        name: Name for the merged sourcelinks target
+        sourcelinks: List of sourcelinks JSON file targets
     """
-    Creates all targets related to documentation.
+
+    native.genrule(
+        name = name,
+        srcs = sourcelinks,
+        outs = [name + ".json"],
+        cmd = """
+        $(location @score_docs_as_code//scripts_bazel:merge_sourcelinks) \
+            --output $@ \
+            $(SRCS)
+        """,
+        tools = ["@score_docs_as_code//scripts_bazel:merge_sourcelinks"],
+    )
+
+def docs(source_dir = "docs", data = [], deps = [], sourcelinks = []):
+    """Creates all targets related to documentation.
+
     By using this function, you'll get any and all updates for documentation targets in one place.
+
+    Args:
+      source_dir: The source directory containing documentation files. Defaults to "docs".
+      data: Additional data files to include in the documentation build.
+      deps: Additional dependencies for the documentation build.
+      sourcelinks: Source code links configuration for traceability.
     """
 
+    _merge_sourcelinks(name = "merged_sourcelinks", sourcelinks = sourcelinks)
+
     call_path = native.package_name()
 
     if call_path != "":
@@ -106,64 +134,69 @@ def docs(source_dir = "docs", data = [], deps = []):
         name = "docs",
         tags = ["cli_help=Build documentation:\nbazel run //:docs"],
         srcs = ["@score_docs_as_code//src:incremental.py"],
-        data = data,
+        data = data + [":merged_sourcelinks"],
         deps = deps,
         env = {
             "SOURCE_DIRECTORY": source_dir,
             "DATA": str(data),
             "ACTION": "incremental",
+            "SCORE_SOURCELINKS": "$(location :merged_sourcelinks)",
         },
     )
 
     py_binary(
         name = "docs_combo_experimental",
         tags = ["cli_help=Build full documentation with all dependencies:\nbazel run //:docs_combo_experimental"],
         srcs = ["@score_docs_as_code//src:incremental.py"],
-        data = data_with_docs_sources,
+        data = data_with_docs_sources + [":merged_sourcelinks"],
         deps = deps,
         env = {
             "SOURCE_DIRECTORY": source_dir,
             "DATA": str(data_with_docs_sources),
             "ACTION": "incremental",
+            "SCORE_SOURCELINKS": "$(location :merged_sourcelinks)",
         },
     )
 
     py_binary(
         name = "docs_check",
         tags = ["cli_help=Verify documentation:\nbazel run //:docs_check"],
         srcs = ["@score_docs_as_code//src:incremental.py"],
-        data = data,
+        data = data + [":merged_sourcelinks"],
         deps = deps,
         env = {
             "SOURCE_DIRECTORY": source_dir,
             "DATA": str(data),
             "ACTION": "check",
+            "SCORE_SOURCELINKS": "$(location :merged_sourcelinks)",
         },
     )
 
     py_binary(
         name = "live_preview",
         tags = ["cli_help=Live preview documentation in the browser:\nbazel run //:live_preview"],
         srcs = ["@score_docs_as_code//src:incremental.py"],
-        data = data,
+        data = data + [":merged_sourcelinks"],
         deps = deps,
         env = {
             "SOURCE_DIRECTORY": source_dir,
             "DATA": str(data),
             "ACTION": "live_preview",
+            "SCORE_SOURCELINKS": "$(location :merged_sourcelinks)",
         },
     )
 
     py_binary(
         name = "live_preview_combo_experimental",
         tags = ["cli_help=Live preview full documentation with all dependencies in the browser:\nbazel run //:live_preview_combo_experimental"],
         srcs = ["@score_docs_as_code//src:incremental.py"],
-        data = data_with_docs_sources,
+        data = data_with_docs_sources + [":merged_sourcelinks"],
         deps = deps,
         env = {
             "SOURCE_DIRECTORY": source_dir,
             "DATA": str(data_with_docs_sources),
             "ACTION": "live_preview",
+            "SCORE_SOURCELINKS": "$(location :merged_sourcelinks)",
         },
     )
 
@@ -193,3 +226,29 @@ def docs(source_dir = "docs", data = [], deps = []):
         tools = data,
         visibility = ["//visibility:public"],
     )
+
+def sourcelinks_json(name, srcs, visibility = None):
+    """
+    Creates a target that generates a JSON file with source code links.
+
+    See https://eclipse-score.github.io/docs-as-code/main/how-to/source_to_doc_links.html
+
+    Args:
+        name: Name of the target
+        srcs: Source files to scan for traceability tags
+        visibility: Visibility of the target
+    """
+    output_file = name + ".json"
+
+    native.genrule(
+        name = name,
+        srcs = srcs,
+        outs = [output_file],
+        cmd = """
+        $(location @score_docs_as_code//scripts_bazel:generate_sourcelinks) \
+            --output $@ \
+            $(SRCS)
+        """,
+        tools = ["@score_docs_as_code//scripts_bazel:generate_sourcelinks"],
+        visibility = visibility,
+    )

docs/concepts/docs_deps.rst

@@ -0,0 +1,41 @@
+
+.. _docs_dependencies:
+
+==========================
+Docs Dependencies
+==========================
+
+When running ``bazel run :docs``, the documentation build system orchestrates multiple interconnected dependencies to produce HTML documentation.
+
+1. Gather inputs (Bazel may do this parallelized):
+
+   * Extract source code links from files via ``sourcelinks_json`` rule.
+
+     * Optionally, merge source links using the ``merge_sourcelinks`` rule.
+
+   * Needs (requirements) are gathered from various ``needs_json`` targets specified in the ``data`` attribute.
+
+2. Documentation sources are read from the specified source directory (default: ``docs/``).
+   Sphinx processes the documentation sources along with the merged data to generate the final HTML output.
+
+.. plantuml::
+
+	 @startuml
+    left to right direction
+
+	 collections "Documentation Sources" as DocsSource
+	 collections "Needs JSON Targets" as NeedsTargets
+	 collections "Source Code Links" as SourceLinks
+	 artifact "Merge Data" as Merge
+	 process "Sphinx Processing" as Sphinx
+	 artifact "HTML Output" as HTMLOutput
+    collections "S-CORE extensions" as SCoreExt
+
+	 DocsSource --> Sphinx
+	 NeedsTargets --> Sphinx
+    SCoreExt --> Sphinx
+	 SourceLinks --> Merge
+	 Merge --> Sphinx
+	 Sphinx --> HTMLOutput
+
+	 @enduml

docs/concepts/index.rst

@@ -9,3 +9,4 @@ Here you find explanations how and why docs-as-code works the way it does.
    :maxdepth: 1
 
    bidirectional_traceability
+   docs_deps

docs/how-to/source_to_doc_links.rst

@@ -2,14 +2,65 @@ Reference Docs in Source Code
 =============================
 
 In your C++/Rust/Python source code, you want to reference requirements (needs).
-The docs-as-code tool will create backlinks in the documentation.
+The docs-as-code tool will create backlinks in the documentation in two steps:
+
+1. You add a special comment in your source code that references the need ID.
+2. Scan for those comments and provide needs links to your documentation.
+
+For an example result, look at the attribute ``source_code_link``
+of :need:`tool_req__docs_common_attr_title`.
+
+Comments in Source Code
+-----------------------
 
 Use a comment and start with ``req-Id:`` or ``req-traceability:`` followed by the need ID.
 
 .. code-block:: python
 
-	 # req-Id: TOOL_REQ__EXAMPLE_ID
-	 # req-traceability: TOOL_REQ__EXAMPLE_ID
+    # req-Id: TOOL_REQ__EXAMPLE_ID
+    # req-traceability: TOOL_REQ__EXAMPLE_ID
 
-For an example, look at the attribute ``source_code_link``
-of :need:`tool_req__docs_common_attr_title`.
+For other languages (C++, Rust, etc.), use the appropriate comment syntax.
+
+Scanning Source Code for Links
+------------------------------
+
+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.
+
+
+.. code-block:: starlark
+   :emphasize-lines: 1, 12, 26
+   :linenos:
+
+   load("//:docs.bzl", "docs", "sourcelinks_json")
+
+   filegroup(
+      name = "some_sources",
+      srcs = [
+          "foo.py",
+          "bar.cpp",
+          "data.yaml",
+      ] + glob(["subdir/**/.py"]),
+   )
+
+   sourcelinks_json(
+      name = "my_source_links",
+      srcs = [
+         ":some_sources",
+         "//src:all_sources",
+         # whatever
+      ],
+   )
+
+   docs(
+      data = [
+             "@score_process//:needs_json",
+         ],
+         source_dir = "docs",
+         sourcelinks = [":my_source_links"],
+   )
+
+Since the source links are Bazel targets, you can easily reference other modules as well.

scripts/README.md

@@ -0,0 +1,3 @@
+# Scripts
+
+The scripts directory is only for local development (linters) so far.

scripts_bazel/BUILD

@@ -0,0 +1,38 @@
+# *******************************************************************************
+# Copyright (c) 2026 Contributors to the Eclipse Foundation
+#
+# See the NOTICE file(s) distributed with this work for additional
+# information regarding copyright ownership.
+#
+# This program and the accompanying materials are made available under the
+# terms of the Apache License Version 2.0 which is available at
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# SPDX-License-Identifier: Apache-2.0
+# *******************************************************************************
+
+load("@aspect_rules_py//py:defs.bzl", "py_binary")
+load("@pip_process//:requirements.bzl", "all_requirements")
+
+filegroup(
+    name = "sources",
+    srcs = glob(["**/*.py"]),
+    visibility = ["//visibility:public"],
+)
+
+py_binary(
+    name = "generate_sourcelinks",
+    srcs = ["generate_sourcelinks_cli.py"],
+    main = "generate_sourcelinks_cli.py",
+    visibility = ["//visibility:public"],
+    deps = [
+        "//src/extensions/score_source_code_linker",
+    ] + all_requirements,
+)
+
+py_binary(
+    name = "merge_sourcelinks",
+    srcs = ["merge_sourcelinks.py"],
+    main = "merge_sourcelinks.py",
+    visibility = ["//visibility:public"],
+)

scripts_bazel/README.md

@@ -0,0 +1,3 @@
+# Scripts Bazel
+
+This folder contains executables to be used within Bazel rules.