feat: allow non root docs()

.gitignore

@@ -9,8 +9,8 @@ user.bazelrc
 .ruff_cache
 
 # docs build artifacts
-/_build*
-docs/ubproject.toml
+_build/
+ubproject.toml
 
 # Vale - editorial style guide
 .vale.ini

docs.bzl

@@ -127,7 +127,7 @@ def _missing_requirements(deps):
         fail(msg)
     fail("This case should be unreachable?!")
 
-def docs(source_dir = "docs", data = [], deps = [], scan_code = [], known_good = None, metamodel = None):
+def docs(source_dir = "docs", data = [], deps = [], scan_code = [], test_sources = [], known_good = None, metamodel = None):
     """Creates all targets related to documentation.
 
     By using this function, you'll get any and all updates for documentation targets in one place.
@@ -137,16 +137,13 @@ def docs(source_dir = "docs", data = [], deps = [], scan_code = [], known_good =
       data: Additional data files to include in the documentation build.
       deps: Additional dependencies for the documentation build.
       scan_code: List of code targets to scan for source code links.
+      test_sources: Optional list of repo-relative directory paths which will be used to filter testcases for documentation generation.
+                    When empty (default), all testcases found in `bazel-testlogs` will be used.
       known_good: Optional label to a "known good" JSON file for source links.
       metamodel: Optional label to a metamodel.yaml file. When set, the extension loads this
                  file instead of the default metamodel shipped with score_metamodel.
     """
 
-    call_path = native.package_name()
-
-    if call_path != "":
-        fail("docs() must be called from the root package. Current package: " + call_path)
-
     metamodel_data = []
     metamodel_env = {}
     metamodel_opts = []
@@ -207,12 +204,16 @@ def docs(source_dir = "docs", data = [], deps = [], scan_code = [], known_good =
 
     docs_env = {
         "SOURCE_DIRECTORY": source_dir,
+        "PACKAGE_DIR": native.package_name(),
         "DATA": str(data),
+        "TEST_SOURCES": str(test_sources),
         "SCORE_SOURCELINKS": "$(location :sourcelinks_json)",
     } | metamodel_env
     docs_sources_env = {
         "SOURCE_DIRECTORY": source_dir,
+        "PACKAGE_DIR": native.package_name(),
         "DATA": str(data_with_docs_sources),
+        "TEST_SOURCES": str(test_sources),
         "SCORE_SOURCELINKS": "$(location :merged_sourcelinks)",
     } | metamodel_env
     if known_good:
@@ -342,8 +343,8 @@ def _sourcelinks_json(name, srcs):
     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
+      name: Name of the target.
+      srcs: Source files to scan for traceability tags.
     """
     output_file = name + ".json"
 

docs/how-to/index.rst

@@ -25,7 +25,6 @@ Here you find practical guides on how to use docs-as-code.
    get_started
    setup
    write_docs
-   faq
    other_modules
    dashboards_and_quality_gates
    source_to_doc_links

src/extensions/score_metamodel/external_needs.py

@@ -31,10 +31,16 @@ class ExternalNeedsSource:
     bazel_module: str
     path_to_target: str
     target: str
+    # True for a same-repo mount (`//pkg:needs_json`), whose runfiles live under
+    # `_main/…`. False for a cross-module mount (`@repo//…:needs_json`), whose
+    # runfiles live under `{bazel_module}+/…`.
+    is_local: bool = False
 
 
 def _parse_bazel_external_need(s: str) -> ExternalNeedsSource | None:
-    if not s.startswith("@"):
+    is_cross_module = s.startswith("@")
+    is_local = s.startswith("//")
+    if not is_cross_module and not is_local:
         # Local need, not external needs
         return None
 
@@ -46,16 +52,28 @@ def _parse_bazel_external_need(s: str) -> ExternalNeedsSource | None:
         ":", 1
     )  # @score_process//:needs_json => [@score_process//, needs_json]
     repo, path_to_target = repo_and_path.split("//", 1)
-    repo = repo.lstrip("@")
+    repo = repo.lstrip("@")  # empty for same-repo `//pkg:needs_json`
 
-    if path_to_target == "" and target in ("needs_json", "docs_sources"):
+    if target in ("needs_json", "docs_sources"):
         return ExternalNeedsSource(
-            bazel_module=repo, path_to_target=path_to_target, target=target
+            bazel_module=repo,
+            path_to_target=path_to_target,
+            target=target,
+            is_local=is_local,
         )
     # Unknown data target. Probably not a needs.json file.
     return None
 
 
+def _runfiles_module_dir(e: ExternalNeedsSource) -> str:
+    """Runfiles top-level directory holding this source's package tree.
+
+    Same-repo mounts are staged under `_main/…`; cross-module mounts under the
+    module's bzlmod canonical name `{bazel_module}+/…`.
+    """
+    return "_main" if e.is_local else f"{e.bazel_module}+"
+
+
 def parse_external_needs_sources_from_DATA(v: str) -> list[ExternalNeedsSource]:
     if v in ["[]", ""]:
         return []
@@ -150,7 +168,13 @@ def get_external_needs_source(external_needs_source: str) -> list[ExternalNeedsS
 
 
 def add_external_needs_json(e: ExternalNeedsSource, config: Config):
-    json_file_raw = f"{e.bazel_module}+/{e.target}/_build/needs/needs.json"
+    json_file_raw = (
+        Path(_runfiles_module_dir(e))
+        / e.path_to_target
+        / e.target
+        / "_build/needs/needs.json"
+    )
+
     r = get_runfiles_dir()
     json_file = r / json_file_raw
     logger.debug(f"External needs.json: {json_file}")
@@ -176,22 +200,28 @@ def add_external_needs_json(e: ExternalNeedsSource, config: Config):
 
 def add_external_docs_sources(e: ExternalNeedsSource, config: Config):
     # Note that bazel does NOT write the files under e.target!
-    # {e.bazel_module}+ matches the original git layout!
+    # The runfiles layout mirrors the original git layout: same-repo mounts live
+    # under `_main/…`, cross-module mounts under `{e.bazel_module}+/…`
+    # (see _runfiles_module_dir).
     r = get_runfiles_dir()
     if "ide_support.runfiles" in str(r):
         logger.error("Combo builds are currently only supported with Bazel.")
         return
-    docs_source_path = Path(r) / f"{e.bazel_module}+"
+    docs_source_path = Path(r) / _runfiles_module_dir(e) / e.path_to_target
+
+    # A cross-module root mount keeps its module name as the collection key
+    # (unchanged). Sub-package / same-repo mounts disambiguate via the path.
+    key = "/".join(c for c in (e.bazel_module, e.path_to_target) if c) or "_main"
 
     if "collections" not in config:
         config.collections = {}
-    config.collections[e.bazel_module] = {
+    config.collections[key] = {
         "driver": "symlink",
         "source": str(docs_source_path),
-        "target": e.bazel_module,
+        "target": key,
     }
 
-    logger.info(f"Added external docs source: {docs_source_path} -> {e.bazel_module}")
+    logger.info(f"Added external docs source: {docs_source_path} -> {key}")
 
 
 def connect_external_needs(app: Sphinx, config: Config):
@@ -204,8 +234,6 @@ def connect_external_needs(app: Sphinx, config: Config):
     config.needs_external_needs = []
 
     for e in external_needs:
-        assert not e.path_to_target  # path_to_target is always empty
-
         if e.target == "needs_json":
             add_external_needs_json(e, app.config)
         elif e.target == "docs_sources":

src/extensions/score_metamodel/tests/rst/options/test_options_failure_effect.rst

@@ -158,7 +158,7 @@
 .. feat_saf_fmea:: Empty failure_effect
    :id: feat_saf_fmea__test__empty_failure_effect
    :fault_id: FMEA_05
-   :failure_effect: 
+   :failure_effect:
    :sufficient: yes
    :status: valid
    :expect: feat_saf_fmea__test__empty_failure_effect: is missing required attribute: `failure_effect`.