docs: glossary, keyword matching and tool-tips

docs/concepts/glossary.md

@@ -1,9 +1,2 @@
-# openpilot glossary
-
-* **onroad**: openpilot's system state while ignition is on
-* **offroad**: openpilot's system state while ignition is off
-* **route**: a route is a recording of an onroad session
-* **segment**: routes are split into one minute chunks called segments.
-* **comma connect**: the web viewer for all your routes; check it out at [connect.comma.ai](https://connect.comma.ai).
-* **panda**: this is the secondary processor on the device that implements the functional safety and directly talks to the car over CAN. See the [panda repo](https://github.com/commaai/panda).
-* **comma 3X**: the latest hardware by comma.ai for running openpilot. more info at [comma.ai/shop](https://comma.ai/shop).
+# Glossary
+{{GLOSSARY_DEFINITIONS}}

docs/css/tooltip.css

@@ -0,0 +1,31 @@
+[data-tooltip] {
+  position: relative;
+  display: inline-block;
+  border-bottom: 1px dotted black;
+}
+
+[data-tooltip] .tooltip-content {
+  width: max-content;
+  max-width: 25em;
+  position: absolute;
+  top: 100%;
+  left: 50%;
+  transform: translateX(-50%);
+  background-color: white;
+  color: #404040;
+  box-shadow: 0 4px 14px 0 rgba(0,0,0,.2), 0 0 0 1px rgba(0,0,0,.05);
+  padding: 10px;
+  font: 14px/1.5 Lato, proxima-nova, Helvetica Neue, Arial, sans-serif;
+  text-decoration: none;
+  opacity: 0;
+  visibility: hidden;
+  transition: opacity 0.1s, visibility 0s;
+  z-index: 1000;
+  pointer-events: none; /* Prevent accidental interaction */
+}
+
+[data-tooltip]:hover .tooltip-content {
+  opacity: 1;
+  visibility: visible;
+  pointer-events: auto; /* Allow interaction when visible */
+}

docs/glossary.toml

@@ -0,0 +1,42 @@
+[glossary]
+
+  [glossary.openpilot_terms]
+  big_model = { description = "A new paradigm in model development that takes a bigger input frame. Full frame is 1164x874, little model is a 512x256 crop, big model is a 1024x512 crop, 4x bigger than little. Make box bigger, drive better. Useful for signs and lights.", abbreviation = "" }
+  driving_model = { description = "The resulting neural network after Comma trains on driving data on their supercomputer. This file lives on the device, and processes inputs to give outputs relevant to driving. Usually takes the form of an ONNX file, or a THNEED file after compilation on device. This file does not change or get trained on device, only processes inputs and outputs. See [the list of driving models](https://github.com/commaai/openpilot/wiki/Driving-Models) for names and details of models over time.", abbreviation = "model" }
+  end_to_end = { description = "End to end means the model reacts like a human would. It assesses the whole picture and acts accordingly. Unlike other approaches where things must be labeled by hand, end to end learns all the nuances of driving. A model is basically trained on what human drivers would do in a certain situation and attempts to reproduce that behavior.", abbreviation = "e2e" }
+  longitudinal = { description = "Refers to gas and brake control.", abbreviation = "long" }
+  lateral = { description = "Refers to steering control.", abbreviation = "lat" }
+  model_predictive_control = { description = "An advanced method of process control that is used to control a process while satisfying a set of constraints. Used for longitudinal and lateral control.", abbreviation = "mpc" }
+  lead = { description = "Selected radar point from your car's radar by the driving model of openpilot using the camera. Used for longitudinal MPC. Usual attributes: distance, speed, and acceleration.", abbreviation = "" }
+  onroad = { description = "openpilot's system state while ignition is on.", abbreviation = "" }
+  offroad = { description = "openpilot's system state while ignition is off.", abbreviation = "" }
+  route = { description = "A route is a recording of an onroad session.", abbreviation = "" }
+  segment = { description = "Routes are split into one minute chunks called segments.", abbreviation = "" }
+  comma_connect = { description = "The web viewer for all your routes; check it out at [connect.comma.ai](https://connect.comma.ai).", abbreviation = "" }
+  panda = { description = "This is the secondary processor on the device that implements the functional safety and directly talks to the car over CAN. See the [panda repo](https://github.com/commaai/panda).", abbreviation = "" }
+  comma_3x = { description = "The latest hardware by comma.ai for running openpilot. More info at [comma.ai/shop](https://comma.ai/shop).", abbreviation = "" }
+
+  [glossary.driver_assistance_terms]
+  adaptive_cruise_control = { description = "A cruise control system that automatically adjusts the vehicle speed to maintain a safe distance from vehicles ahead.", abbreviation = "ACC" }
+  advanced_driver_assistance_systems = { description = "Electronic systems that aid the driver.", abbreviation = "ADAS" }
+  lane_centering = { description = "A system designed to keep a car centered in the lane, relieving the driver of the task of steering.", abbreviation = "(A)LC" }
+  collision_avoidance_system = { description = "A system designed to prevent or reduce the severity of a collision.", abbreviation = "AEB, CMS, FCW(S), FCA, PCS" }
+  driver_monitoring_system = { description = "A system that uses infrared sensors and/or cameras to monitor driver attentiveness.", abbreviation = "DM(S), DAM" }
+  dynamic_range_cruise_control = { description = "A cruise control system that automatically adjusts the vehicle speed to maintain a safe distance from vehicles ahead.", abbreviation = "DRCC" }
+  hugging = { description = "An undesired behavior where the vehicle drives too closely to one side of the lane.", abbreviation = "" }
+  lane_keep_assist_system = { description = "Lane keep assist is what comes with most cars sold today. It will assist the driver if they go over a lane line, but will not keep the car centered in the lane.", abbreviation = "LKA(S)" }
+  lane_departure_warning_system = { description = "Lane departure warning will beep when a car goes over a lane line.", abbreviation = "LDW(S), LDA" }
+  pedestrian_crash_avoidance_mitigation = { description = "A system that uses computer and artificial intelligence technology to recognize pedestrians and bicycles in an automobile's path to take action for safety.", abbreviation = "PCAM" }
+  ping_pong = { description = "An undesired behavior where the vehicle sways from one side of the lane to the other repeatedly. The desired behavior is to stay in the center of the lane.", abbreviation = "" }
+  wobble = { description = "Similar to ping pong, but where the vehicle drives mostly centered in the lane but sways slightly from side to side. Primarily due to improper tuning of the steering control system, influence from wind, or poor lane/path perception due to rain, dirt, and/or debris on the vehicles windshield.", abbreviation = "" }
+  traffic_sign_recognition = { description = "A system by which a vehicle is able to recognize the traffic signs put on the road e.g. \"speed limit\" or \"children\" or \"turn ahead\".", abbreviation = "TSR" }
+  stop_and_go = { description = "The ability for the car to be brought to a standstill and then resume driving without needing to disengage or reengage openpilot.", abbreviation = "SnG" }
+  vision_only_adaptive_cruise_control = { description = "The exclusive use of cameras instead of radar to provide adaptive cruise control functions.", abbreviation = "VOACC" }
+
+  [glossary.automotive_terms]
+  controller_area_network = { description = "A message-based protocol that provides a standardized way for ECUs to communicate with each other.", abbreviation = "CAN, CAN bus" }
+  can_fd = { description = "A newer version of CAN that supports higher data rates and longer messages. A red panda is required to interface with CAN-FD vehicles.", abbreviation = "" }
+  electronic_control_unit = { description = "Any embedded system in automotive electronics that controls one or more of the electrical systems or subsystems in a vehicle.", abbreviation = "ECU" }
+  electric_power_steering = { description = "Uses an electric motor to assist the driver of a vehicle. Sensors detect the position and torque of the steering column, and a computer module applies assistive torque via the motor, which connects to either the steering gear or steering column.", abbreviation = "EPS" }
+  onboard_diagnostics_connector = { description = "OBD systems give the vehicle owner or repair technician access to the status of the various vehicle sub-systems. The comma power v2 uses this port to provide constant power to the comma two as well as access the diagnostic bus for FW query.", abbreviation = "OBD-II, OBD-II port" }
+  full_self_driving = { description = "A term often used to describe systems designed to automate the entire driving process, potentially eliminating the need for human intervention. In the context of openpilot, this represents the goal of achieving a high level of autonomy where the system handles navigation, decision-making, and vehicle control across various environments.", abbreviation = "FSD" }

docs/hooks/glossary.py

@@ -0,0 +1,55 @@
+import re
+import tomllib
+
+with open("docs/glossary.toml", "rb") as f:
+  glossary_data = tomllib.load(f)
+
+glossary = glossary_data.get("glossary", {})
+
+def glossary_markdown(glossary):
+  markdown_string = ""
+
+  # Iterate over each category and terms
+  for category, terms in glossary.items():
+    markdown_string += f"## {category.replace('_', ' ').title()}\n"
+
+    for name, definition in terms.items():
+      markdown_string += f"* **{name.replace('_', ' ').title()}**"
+      if "abbreviation" in definition and definition["abbreviation"]:
+        markdown_string += f" *({definition['abbreviation']})*"
+      if "description" in definition and definition["description"]:
+        markdown_string += f": {definition['description']}\n"
+
+  return markdown_string
+
+
+def tooltip_html(glossary, html):
+  for category, terms in glossary.items():
+    for term, definition in terms.items():
+      if "description" in definition and definition["description"]:
+        # Removes Markdown link formatting, but keeps the link text
+        clean_description = re.sub(r"\[(.+)]\(.+\)", r"\1", definition["description"])
+
+        # Embed a tooltip-content element
+        html = re.sub(
+          re.escape(term),
+          lambda match, descr=clean_description: (
+            f"<span data-tooltip>{match.group(0)}"
+            f"<span class='tooltip-content'>{descr}</span>"
+            f"</span>"
+          ),
+          html,
+          flags=re.IGNORECASE,
+        )
+  return html
+
+def on_page_markdown(markdown, **kwargs):
+  return markdown.replace("{{GLOSSARY_DEFINITIONS}}", glossary_markdown(glossary))
+
+
+def on_page_content(html, **kwargs):
+  # Don't add tooltips to the glossary page
+  if kwargs.get("page").title == "Glossary":
+    return html
+  else:
+    return tooltip_html(glossary, html)

mkdocs.yml

@@ -8,6 +8,11 @@ strict: true
 docs_dir: docs
 site_dir: docs_site/
 
+hooks:
+  - docs/hooks/glossary.py
+extra_css:
+  - css/tooltip.css
+
 theme:
   name: readthedocs
   navigation_depth: 3
@@ -31,7 +36,7 @@ nav:
   - Contributing:
     - Roadmap: contributing/roadmap.md
     #- Architecture: contributing/architecture.md
-    - Contributing Guide →: https://github.com/commaai/openpilot/blob/master/docs/CONTRIBUTING.md
+    - Contributing Guide: CONTRIBUTING.md
   - Links:
     - Blog →: https://blog.comma.ai
     - Bounties →: https://comma.ai/bounties