docs: glossary, keyword matching and tool-tips

.github/workflows/docs.yaml

@@ -18,7 +18,7 @@ concurrency:
 jobs:
   docs:
     name: build docs
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
     - uses: commaai/timeout@v1
 

docs/CONTRIBUTING.md

@@ -14,23 +14,24 @@ Development is coordinated through [Discord](https://discord.comma.ai) and GitHu
 ## What contributions are we looking for?
 
 **openpilot's priorities are [safety](SAFETY.md), stability, quality, and features, in that order.**
-openpilot is part of comma's mission to *solve self-driving cars while delivering shippable intermediaries*, and all development is towards that goal. 
+openpilot is part of comma's mission to *solve self-driving cars while delivering shippable intermediaries*, and all development is towards that goal.
 
 ### What gets merged?
 
 The probability of a pull request being merged is a function of its value to the project and the effort it will take us to get it merged.
 If a PR offers *some* value but will take lots of time to get merged, it will be closed.
-Simple, well-tested bug fixes are the easiest to merge, and new features are the hardest to get merged. 
+Simple, well-tested bug fixes are the easiest to merge, and new features are the hardest to get merged.
 
 All of these are examples of good PRs:
-* typo fix: https://github.com/commaai/openpilot/pull/30678
-* removing unused code: https://github.com/commaai/openpilot/pull/30573
-* simple car model port: https://github.com/commaai/openpilot/pull/30245
-* car brand port: https://github.com/commaai/openpilot/pull/23331
+
+* typo fix: [#30678](https://github.com/commaai/openpilot/pull/30678)
+* removing unused code: [#30573](https://github.com/commaai/openpilot/pull/30573)
+* simple car model port: [#30245](https://github.com/commaai/openpilot/pull/30245)
+* car brand port: [#23331](https://github.com/commaai/openpilot/pull/23331)
 
 ### What doesn't get merged?
 
-* **style changes**: code is art, and it's up to the author to make it beautiful 
+* **style changes**: code is art, and it's up to the author to make it beautiful
 * **500+ line PRs**: clean it up, break it up into smaller PRs, or both
 * **PRs without a clear goal**: every PR must have a singular and clear goal
 * **UI design**: we do not have a good review process for this yet

docs/car-porting/brand-port.md

@@ -2,4 +2,4 @@
 
 A brand port is a port of openpilot to a substantially new car brand or platform within a brand.
 
-Here's an example of one: https://github.com/commaai/openpilot/pull/23331.
+Here's an example of one: [PR-23331](https://github.com/commaai/openpilot/pull/23331).

docs/car-porting/model-port.md

@@ -2,4 +2,4 @@
 
 A model port is a port of openpilot to a new car model within an already supported brand. Model ports are easier than brand ports because the car's existing APIs are already known.
 
-Here's an example of one: https://github.com/commaai/openpilot/pull/30672/.
+Here's an example of one: [PR-30672](https://github.com/commaai/openpilot/pull/30672/).

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,44 @@
+[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 */
+}
+
+.tooltip-content .tooltip-glossary-link {
+  display: inline-block;
+  margin-top: 8px;
+  font-size: 12px;
+  color: #007bff;
+  text-decoration: none;
+}
+
+.tooltip-content .tooltip-glossary-link:hover {
+  color: #0056b3;
+  text-decoration: underline;
+}

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 <a href='https://github.com/commaai/openpilot/wiki/Driving-Models'target='_blank'>the list of driving models</a> 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 <a href='https://connect.comma.ai'target='_blank'>connect.comma.ai</a>", 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 <a href='https://github.com/commaai/panda' target='_blank'>panda repo</a>.", abbreviation = "" }
+  comma_3x = { description = "The latest hardware by comma.ai for running openpilot. More info at <a href='https://comma.ai/shop'target='_blank'>comma.ai/shop</a>.", 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,67 @@
+import re
+import tomllib
+
+with open("docs/glossary.toml", "rb") as f:
+  glossary_data = tomllib.load(f)
+
+glossary = glossary_data.get("glossary", {})
+
+def generate_anchor_id(name):
+  return name.replace(" ", "-").replace("_", "-").lower()
+
+def format_markdown_term(name, definition):
+  anchor_id = generate_anchor_id(name)
+  markdown = f"* [**{name.replace('_', ' ').title()}**](#{anchor_id})"
+  if definition.get("abbreviation"):
+    markdown += f" *({definition['abbreviation']})*"
+  if definition.get("description"):
+    markdown += f": {definition['description']}\n"
+  return markdown
+
+def glossary_markdown(vocabulary):
+  markdown = ""
+  for category, terms in vocabulary.items():
+    markdown += f"## {category.replace('_', ' ').title()}\n\n"
+    for name, definition in terms.items():
+      markdown += format_markdown_term(name, definition)
+  return markdown
+
+def format_tooltip_html(term_key, definition, html):
+  display_term = term_key.replace("_", " ").title()
+  clean_description = re.sub(r"\[(.+)]\(.+\)", r"\1", definition["description"])
+  glossary_link = (
+    f"<a href='/concepts/glossary#{term_key}' class='tooltip-glossary-link' title='View in glossary'>Glossary🔗</a>"
+  )
+  return re.sub(
+    re.escape(display_term),
+    lambda
+      match: f"<span data-tooltip>{match.group(0)}<span class='tooltip-content'>{clean_description} {glossary_link}</span></span>",
+    html,
+    flags=re.IGNORECASE,
+  )
+
+def apply_tooltip(_term_key, _definition, pattern, html):
+  return re.sub(
+  pattern,
+    lambda match: format_tooltip_html(_term_key, _definition, match.group(0)),
+    html,
+    flags=re.IGNORECASE,
+  )
+
+
+def tooltip_html(vocabulary, html):
+  for _category, terms in vocabulary.items():
+    for term_key, definition in terms.items():
+      if definition.get("description"):
+        pattern = rf"(?<!\w){re.escape(term_key.replace('_', ' ').title())}(?![^<]*<\/a>)(?!\([^)]*\))"
+        html = apply_tooltip(term_key, definition, pattern, html)
+  return html
+
+# Page Hooks
+def on_page_markdown(markdown, **kwargs):
+  return markdown.replace("{{GLOSSARY_DEFINITIONS}}", glossary_markdown(glossary))
+
+def on_page_content(html, **kwargs):
+  if kwargs.get("page").title == "Glossary":
+    return html
+  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