Codelinks example in ADAS with C files

crates/coffee-machine/src/ubproject.redirect.toml

@@ -0,0 +1 @@
+path = "../../../docs"

docs/automotive-adas/swe_3_sw_detailed_design.rst

@@ -8,6 +8,18 @@ SWE.3 Detailed Design
 
 This document provides the software implementation documentation as per SWE.1 and SWE.2 requirements.
 
+Codelinks example
+------------------
+Using **C** language.
+
+.. src-trace::
+   :project: adas
+
+Automodule example
+------------------
+Using **Python** language.
+
+
 .. automodule:: automotive_adas
    :members:
    :undoc-members:

docs/conf.py

@@ -10,7 +10,7 @@
 
 # We need to make Python aware of our project source code, which is stored outside `/docs`,
 # under `src/`
-code_path = os.path.join(os.path.dirname(__file__), "../", "src/")
+code_path = os.path.join(os.path.dirname(__file__), "../", "src/python/")
 sys.path.append(code_path)
 print(f"CODE_PATH: {code_path}")
 
@@ -99,7 +99,7 @@
     "selector": "article#furo-main-content a",
     # A list of selectors, where no preview icon shall be added, because it makes often no sense.
     # For instance the own ID of a need object, or the link on an image to open the image.
-    "not_selector": "div.needs_head a, h1 a, h2 a, a.headerlink, a.back-to-top, a.image-reference, em.sig-param a, a.paginate_button, a.sd-btn",
+    "not_selector": "div.needs_head a, h1 a, h2 a, a.headerlink, a.back-to-top, a.image-reference, em.sig-param a, a.paginate_button, a.sd-btn, a[href*='#L'], div.highlight a",
     "set_icon": True,
     "icon_only": True,
     "icon_click": True,

docs/ubproject.toml

@@ -673,6 +673,36 @@ local_url_field = "local-url"   # Need's field name for local URL
 set_remote_url = true           # Enable remote url generation
 remote_url_field = "remote-url" # Need's field name for remote URL
 
+
+# ADAS
+
+# Configuration for the  ADAS c project
+[codelinks.projects.adas]
+remote_url_pattern = "https://github.com/useblocks/sphinx-needs-demo/blob/{commit}/{path}#L{line}"
+
+[codelinks.projects.adas.source_discover]
+src_dir = "../src/c"  # Relative path to Rust source
+gitignore = true
+comment_type ="cpp"
+
+[codelinks.projects.adas.analyse]
+get_need_id_refs = true
+get_oneline_needs = true      # Extract oneline need definitions from code
+
+[codelinks.projects.adas.analyse.oneline_comment_style]
+start_sequence = "@ "         # Start sequence: "// @ "
+field_split_char = ","        # Separator between fields
+# Define the fields in the oneline comments
+needs_fields = [
+  { "name" = "title", "type" = "str" },
+  { "name" = "id", "type" = "str" },
+  { "name" = "type", "type" = "str", "default" = "impl" },
+  { "name" = "implements", "type" = "list[str]", "default" = [] },
+]
+
+
+# COFFE MACHINE
+
 # Configuration for the coffee-machine Rust project
 [codelinks.projects.coffee_machine]
 remote_url_pattern = "https://github.com/useblocks/sphinx-needs-demo/blob/{commit}/{path}#L{line}"

pyproject.toml

@@ -15,7 +15,8 @@ dependencies = [
     "sphinx-test-reports>=1.3.2",  # pin as RTD consumes this file, not uv.lock
     "furo>=2024.8.6",
     "sphinx-preview>=0.1.2",
-    "ubt-sphinx==0.7.1"
+    "ubt-sphinx==0.7.1",
+    "ubt-runtime==0.6.0"
 ]
 readme = "README.md"
 requires-python = ">= 3.12"

src/c/acc.c

@@ -0,0 +1,49 @@
+/**
+ * Adaptive Cruise Control - pseudo-code implementation
+ *
+ * Covers SWREQ_004, SWREQ_005, SWREQ_006, SWREQ_007
+ */
+
+#include "acc.h"
+
+// @ AdaptiveCruiseModule struct, IMPL_ACC_MODULE, impl, [SWREQ_004, SWREQ_005, SWREQ_006, SWREQ_007]
+typedef struct {
+    float distance_m;        /* measured distance to vehicle ahead (m)    */
+    float target_speed_mps;  /* current speed setpoint (m/s)              */
+    float collision_risk;    /* normalised risk score 0.0 – 1.0           */
+    int   emergency_active;  /* 1 when emergency brake has been commanded */
+} AdaptiveCruiseModule;
+
+// @ measure_radar_distance, IMPL_ACC_DISTANCE, impl, [SWREQ_004]
+/**
+ * Read radar return and compute distance to the nearest object ahead.
+ * Updates acc->distance_m with high-precision measurement (±0.1 m).
+ */
+void measure_radar_distance(AdaptiveCruiseModule *acc, const RadarFrame *frame)
+{
+    /* stub: parse frame, calculate distance, write acc->distance_m */
+    (void)acc; (void)frame;
+}
+
+// @ adjust_speed, IMPL_ACC_SPEED, impl, [SWREQ_005, SWREQ_013]
+/**
+ * Dynamically update the speed setpoint based on the measured following
+ * distance, desired headway and detected speed-limit signs.
+ */
+void adjust_speed(AdaptiveCruiseModule *acc, float speed_limit_mps)
+{
+    /* stub: headway control law → write acc->target_speed_mps */
+    (void)acc; (void)speed_limit_mps;
+}
+
+// @ evaluate_collision_risk, IMPL_ACC_RISK, impl, [SWREQ_006, SWREQ_007]
+/**
+ * Compute a collision-risk score from sensor fusion data.
+ * Triggers emergency brake autonomously when risk exceeds critical threshold.
+ */
+void evaluate_collision_risk(AdaptiveCruiseModule *acc, const SensorFusion *sf)
+{
+    /* stub: predictive analytics → set acc->collision_risk;
+             if risk > 0.9 set acc->emergency_active and command brakes */
+    (void)acc; (void)sf;
+}

src/c/lane_keeping.c

@@ -0,0 +1,48 @@
+/**
+ * Lane Keeping Assist - pseudo-code implementation
+ *
+ * Covers SWREQ_001, SWREQ_002, SWREQ_003
+ */
+
+#include "lane_keeping.h"
+
+// @ LaneKeepingModule struct, IMPL_LKA_MODULE, impl, [SWREQ_001, SWREQ_002, SWREQ_003]
+typedef struct {
+    float lane_offset_m;      /* lateral deviation from lane centre */
+    int   markings_valid;     /* 1 = lane markings detected         */
+    float correction_angle;   /* steering correction in degrees     */
+} LaneKeepingModule;
+
+// @ detect_lane_markings, IMPL_LKA_DETECT, impl, [SWREQ_001]
+/**
+ * Process camera frame and update marking validity flag.
+ * Handles rain, fog and low-light conditions via adaptive thresholding.
+ */
+void detect_lane_markings(LaneKeepingModule *lka, const CameraFrame *frame)
+{
+    /* stub: analyse frame, set lka->markings_valid and update lane_offset_m */
+    (void)lka; (void)frame;
+}
+
+// @ check_lane_deviation, IMPL_LKA_DEVIATION, impl, [SWREQ_002]
+/**
+ * Return 1 when lateral offset exceeds the warning threshold and no
+ * turn-signal is active; triggers dashboard / audio warning.
+ */
+int check_lane_deviation(const LaneKeepingModule *lka, int turn_signal_active)
+{
+    /* stub: compare lka->lane_offset_m against threshold */
+    (void)lka; (void)turn_signal_active;
+    return 0;
+}
+
+// @ apply_steering_correction, IMPL_LKA_CORRECTION, impl, [SWREQ_003]
+/**
+ * Calculate corrective steering angle to bring the vehicle back to
+ * lane centre and forward the command to the actuator layer.
+ */
+void apply_steering_correction(LaneKeepingModule *lka)
+{
+    /* stub: compute PID correction, write lka->correction_angle, send to actuator */
+    (void)lka;
+}

src/ubproject.redirect.toml

@@ -0,0 +1 @@
+path = "../docs"