lobster-rst-report

BUILD.bazel

@@ -65,6 +65,7 @@ py_library(
         "lobster-online-report-nogit.py",
         "lobster-python.py",
         "lobster-report.py",
+        "lobster-rst-report.py",
         "lobster-trlc.py",
     ],
     visibility = [
@@ -78,6 +79,7 @@ py_library(
         "//lobster/tools/core/online_report",
         "//lobster/tools/core/online_report_nogit",
         "//lobster/tools/core/report",
+        "//lobster/tools/core/rst_report",
         "//lobster/tools/cpp",
         "//lobster/tools/cpptest",
         "//lobster/tools/gtest",
@@ -143,6 +145,15 @@ py_binary(
     deps = ["//lobster/tools/core/html_report"],
 )
 
+py_binary(
+    name = "lobster-rst-report",
+    srcs = ["lobster-rst-report.py"],
+    visibility = [
+        "//visibility:public",
+    ],
+    deps = ["//lobster/tools/core/rst_report"],
+)
+
 py_binary(
     name = "lobster-json",
     srcs = ["lobster-json.py"],

CHANGELOG.md

@@ -5,7 +5,21 @@
 
 ### 1.0.4-dev
 
-* `trlc bazel dep`: update to trlc==2.0.5
+* `lobster-rst-report`:
+  - New tool: Generate reStructuredText traceability reports for inclusion
+    in Sphinx documentation projects.
+  - Supports single-page (`--out`) and multi-page (`--out-dir`) output modes.
+  - Requires the `sphinx-design` Sphinx extension for dropdown and grid
+    rendering, and `sphinx.ext.graphviz` for the tracing policy diagram.
+  - Includes coverage summary table, tracing policy diagram (Graphviz),
+    issues list, and detailed item cards with cross-references.
+  - Codebeamer items are rendered as clickable hyperlinks.
+  - Bazel integration via `subrule_lobster_rst_report` (opt-in).
+
+* Refactored `is_dot_available()` into `lobster.common.graphviz_utils`
+  (shared between `lobster-html-report` and `lobster-rst-report`).
+
+  * `trlc bazel dep`: update to trlc==2.0.5
 
 * Fixed wrong links in [README](README.md).
 

Makefile

@@ -34,6 +34,7 @@ lint-system-tests: style
 		tests_system/lobster_online_report_nogit \
 		tests_system/lobster_pkg \
 		tests_system/lobster_report \
+		tests_system/lobster_rst_report \
 		tests_system/lobster_trlc \
 		tests_system/system_test_case_base.py
 
@@ -90,7 +91,8 @@ packages: clean-packages
 		lobster-json --version && \
 		lobster-python --version && \
 		lobster-trlc --version && \
-		lobster-pkg --version
+		lobster-pkg --version && \
+		lobster-rst-report --version
 
 clang-tidy:
 	cd .. && \

bazel/private/lobster_test.bzl

@@ -64,6 +64,41 @@ subrule_lobster_html_report = subrule(
     },
 )
 
+def _lobster_rst_report_subrule_impl(ctx, lobster_report, _lobster_rst_report):
+    lobster_rst_report = ctx.actions.declare_file("{}_report.rst".format(ctx.label.name))
+
+    # Compute relative path from the RST output back to the workspace root so
+    # that file references in the report resolve correctly when included in Sphinx.
+    package = ctx.label.package
+    package_depth = len(package.split("/")) if package else 0
+    source_root = "/".join([".." for _ in range(package_depth + 1)]) + "/"
+
+    args = ctx.actions.args()
+    args.add(lobster_report.path)
+    args.add_all(["--out", lobster_rst_report.path])
+    args.add_all(["--source-root", source_root])
+
+    ctx.actions.run(
+        executable = _lobster_rst_report,
+        inputs = [lobster_report],
+        outputs = [lobster_rst_report],
+        arguments = [args],
+        progress_message = "lobster-rst-report {}".format(lobster_rst_report.path),
+    )
+
+    return lobster_rst_report
+
+subrule_lobster_rst_report = subrule(
+    implementation = _lobster_rst_report_subrule_impl,
+    attrs = {
+        "_lobster_rst_report": attr.label(
+            default = "//:lobster-rst-report",
+            executable = True,
+            cfg = "exec",
+        ),
+    },
+)
+
 def _lobster_test_impl(ctx):
     lobster_config_substitutions = {}
     for input_config in ctx.attr.inputs:

documentation/manual-lobster_rst_report.md

@@ -0,0 +1,144 @@
+# lobster-rst-report
+
+Generate reStructuredText (RST) traceability reports from LOBSTER
+report files, for inclusion in a Sphinx documentation project.
+
+## Overview
+
+`lobster-rst-report` converts a `.lobster` report file into RST that
+can be built by Sphinx.  The output uses
+[sphinx-design](https://sphinx-design.readthedocs.io/) directives
+(dropdowns, grids, cards) for a rich presentation and
+[sphinx.ext.graphviz](https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html)
+for the tracing policy diagram.
+
+Two output modes are available:
+
+* **Single-page** (`--out FILE`) — one RST file containing the entire
+  report.
+* **Multi-page** (`--out-dir DIR`) — an `index.rst` plus one RST file
+  per tracing level, linked via `toctree` directives.
+
+## Installation
+
+`lobster-rst-report` is included in the `bmw-lobster-core` and
+`bmw-lobster-monolithic` packages.
+
+Your Sphinx project additionally requires:
+
+```
+pip install sphinx-design
+```
+
+## Usage
+
+```
+lobster-rst-report [LOBSTER_REPORT] [--out FILE | --out-dir DIR] [--source-root PREFIX]
+```
+
+| Argument | Description |
+|---|---|
+| `LOBSTER_REPORT` | Path to the `.lobster` report file (default: `report.lobster`). |
+| `--out FILE` | Write a single-page RST report to `FILE` (default: `lobster_report.rst`). |
+| `--out-dir DIR` | Write a multi-page RST report to `DIR` (index.rst + one page per level). |
+| `--source-root PREFIX` | Prefix prepended to file reference URLs.  Use this when the RST output directory differs from the workspace root. |
+
+`--out` and `--out-dir` are mutually exclusive.
+
+### Choosing `--source-root`
+
+File references in a `.lobster` report are relative to the workspace root
+(e.g. `src/module/foo.cpp`).  `--source-root` turns those paths into
+clickable URLs by prepending a prefix.  A trailing `/` is optional — if it is
+missing, one is added automatically (so both `../../` and `../..` work).
+
+**Example 1 — GitHub permalink** (links point to a specific branch/commit
+on GitHub):
+
+```bash
+lobster-rst-report report.lobster \
+    --out-dir docs/traceability/ \
+    --source-root "https://github.com/org/repo/blob/main/"
+# src/module/foo.cpp  →  https://github.com/org/repo/blob/main/src/module/foo.cpp
+```
+
+**Example 2 — Relative local link** (links point to source files served
+alongside the HTML documentation):
+
+```
+project/
+  src/module/foo.cpp      ← file reference: "src/module/foo.cpp"
+  docs/
+    conf.py
+    traceability/         ← --out-dir target, two levels below project root
+```
+
+```bash
+lobster-rst-report report.lobster \
+    --out-dir docs/traceability/ \
+    --source-root "../../"
+# src/module/foo.cpp  →  ../../src/module/foo.cpp  (relative to the RST file)
+```
+
+If `--source-root` is omitted, file references appear as plain text paths
+without hyperlinks.
+
+### Example
+
+```bash
+# Generate a multi-page RST report
+lobster-rst-report report.lobster --out-dir docs/traceability
+
+# Generate a single-page RST report
+lobster-rst-report report.lobster --out docs/traceability.rst
+```
+
+## Sphinx project setup
+
+Your Sphinx `conf.py` must load the required extensions:
+
+```python
+extensions = ["sphinx_design", "sphinx.ext.graphviz"]
+```
+
+> **Note:** `project`, `author`, and `copyright` are standard Sphinx
+> settings that you configure for your own documentation project.
+> `lobster-rst-report` generates RST content only — it does not create or
+> modify `conf.py`.  Each project sets these values independently.
+
+For multi-page mode, include the generated `index.rst` via a `toctree`
+in your main documentation:
+
+```rst
+.. toctree::
+   :maxdepth: 2
+   :caption: Traceability
+
+   traceability/index
+```
+
+### Optional: custom CSS
+
+The generated RST uses the CSS class `lobster-issue-card` for issue
+message cards.  You can style them in a custom stylesheet:
+
+```css
+.lobster-issue-card .sd-card-body {
+    background-color: #f8d7da;
+}
+.lobster-issue-card {
+    border: 2px solid #dc3545;
+}
+```
+
+## Bazel integration
+
+The tool is available as a Bazel subrule for use in custom rules:
+
+```starlark
+load("//:lobster.bzl", "subrule_lobster_rst_report")
+```
+
+The subrule accepts a `.lobster` report file and produces a single-page
+`.rst` file.  It automatically computes `--source-root` based on the
+package depth so that file reference links resolve correctly.

documentation/user-manual.md

@@ -12,7 +12,7 @@ simplify this. The basic setup is as follows:
 2. Annotate traces onto your code, your tests and/or your requirements. Please notice each one of the supported languages has their own way to annotate the tracing tags.
 3. Extract the requirement traces with the corresponding lobster conversion tools (e.g. `lobster-cpp`). This converts those traces into a *.lobster file (into a "common unified interchange format").
 4. Build report by calling `lobster-report`
-5. Render your report by calling the core losbter tools. Usually a local HTML report is desired via `lobster-html-report` or even `lobster-ci-report` for your CI.
+5. Render your report by calling the core lobster tools. Usually a local HTML report is desired via `lobster-html-report`, an RST report for Sphinx documentation via `lobster-rst-report`, or even `lobster-ci-report` for your CI.
 
 The basic idea is that you have a number of artefacts that you wish to
 relate to each other; stored in different "databases". Sometimes this

lobster-rst-report.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+#
+# LOBSTER - Lightweight Open BMW Software Traceability Evidence Report
+# Copyright (C) 2026 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+# Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public
+# License along with this program. If not, see
+# <https://www.gnu.org/licenses/>.
+
+import sys
+
+from lobster.tools.core.rst_report.rst_report import main
+
+if __name__ == "__main__":
+    sys.exit(main())

lobster.bzl

@@ -2,7 +2,7 @@ load("//bazel:providers.bzl", _LobsterProvider = "LobsterProvider")
 load("//bazel/private:gtest_report.bzl", _gtest_report = "gtest_report", _subrule_gtest_report = "subrule_gtest_report")
 load("//bazel/private:lobster_gtest.bzl", _lobster_gtest = "lobster_gtest", _subrule_lobster_gtest = "subrule_lobster_gtest")
 load("//bazel/private:lobster_raw.bzl", _lobster_raw = "lobster_raw")
-load("//bazel/private:lobster_test.bzl", _lobster_test = "lobster_test", _subrule_lobster_html_report = "subrule_lobster_html_report", _subrule_lobster_report = "subrule_lobster_report")
+load("//bazel/private:lobster_test.bzl", _lobster_test = "lobster_test", _subrule_lobster_html_report = "subrule_lobster_html_report", _subrule_lobster_report = "subrule_lobster_report", _subrule_lobster_rst_report = "subrule_lobster_rst_report")
 load("//bazel/private:lobster_trlc.bzl", _lobster_trlc = "lobster_trlc", _subrule_lobster_trlc = "subrule_lobster_trlc")
 
 # Re-export LobsterProvider so it can be loaded from this file
@@ -26,5 +26,6 @@ def lobster_gtest(**kwargs):
 subrule_lobster_trlc = _subrule_lobster_trlc
 subrule_lobster_gtest = _subrule_lobster_gtest
 subrule_lobster_html_report = _subrule_lobster_html_report
+subrule_lobster_rst_report = _subrule_lobster_rst_report
 subrule_lobster_report = _subrule_lobster_report
 subrule_gtest_report = _subrule_gtest_report

lobster/common/BUILD.bazel

@@ -23,6 +23,7 @@ py_library(
         "exceptions.py",
         "file_collector.py",
         "file_tag_generator.py",
+        "graphviz_utils.py",
         "io.py",
         "items.py",
         "level_definition.py",

lobster/common/graphviz_utils.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+#
+# LOBSTER - Lightweight Open BMW Software Traceability Evidence Report
+# Copyright (C) 2025 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+# Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public
+# License along with this program. If not, see
+# <https://www.gnu.org/licenses/>.
+"""Shared Graphviz utilities for LOBSTER report tools."""
+
+import subprocess
+from typing import Optional
+
+
+def is_dot_available(dot: Optional[str] = None) -> bool:
+    """Return True if the ``dot`` executable (Graphviz) is on PATH.
+
+    Args:
+        dot: Optional explicit path to the ``dot`` binary.  When ``None``
+            (default) the system PATH is searched.
+
+    Returns:
+        ``True`` if Graphviz ``dot`` is available, ``False`` otherwise.
+    """
+    try:
+        subprocess.run(
+            [dot if dot else "dot", "-V"],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            encoding="UTF-8",
+            check=True,
+            timeout=5,
+        )
+        return True
+    except (FileNotFoundError, subprocess.TimeoutExpired,
+            subprocess.CalledProcessError):
+        return False