From 691d0d3a138681e9ca8f720fe9ea09d7ea4dce81 Mon Sep 17 00:00:00 2001 From: Brandon Shrewsbury Date: Fri, 22 May 2026 10:41:35 -0600 Subject: [PATCH 1/3] Add Component and Service API overview pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add two new "Overview" pages — one under Reference > APIs > Component APIs, one under Reference > APIs > Service APIs — that render every API type and its methods in a compact CSS grid. Selecting an API name opens its full reference; selecting a method jumps to that method's anchor. Method data is read at Hugo build time from the existing auto-generated per-API `-table.md` includes via the new `api-overview` shortcode, so the grid can never drift from the per-API detail pages. - data/{component,service}_apis.yaml: API title/link/table-include map - layouts/shortcodes/api-overview.html: renders the grid from a data file - docs/reference/apis/{components,services}/overview.md: the new pages - assets/scss/_styles_project.scss: .api-overview-grid / .api-method-chip - docs/reference/apis/_index.md: discoverability cards to both pages Co-Authored-By: Claude Opus 4.7 (1M context) --- assets/scss/_styles_project.scss | 50 ++++++++++++++++++ data/component_apis.yaml | 59 ++++++++++++++++++++++ data/service_apis.yaml | 31 ++++++++++++ docs/reference/apis/_index.md | 16 ++++++ docs/reference/apis/components/overview.md | 12 +++++ docs/reference/apis/services/overview.md | 12 +++++ layouts/shortcodes/api-overview.html | 37 ++++++++++++++ 7 files changed, 217 insertions(+) create mode 100644 data/component_apis.yaml create mode 100644 data/service_apis.yaml create mode 100644 docs/reference/apis/components/overview.md create mode 100644 docs/reference/apis/services/overview.md create mode 100644 layouts/shortcodes/api-overview.html diff --git a/assets/scss/_styles_project.scss b/assets/scss/_styles_project.scss index b06a7ad257..9901302dca 100644 --- a/assets/scss/_styles_project.scss +++ b/assets/scss/_styles_project.scss @@ -4090,3 +4090,53 @@ footer { } /* Feedback System Styles END */ + +/* API overview grid START */ + +.api-overview-grid { + display: grid; + grid-template-columns: repeat(auto-fill, minmax(280px, 1fr)); + gap: 1rem; + margin: 1.5rem 0 2rem; +} + +.api-overview-card { + border: 1px solid #dee2e6; + border-radius: 4px; + padding: 0.75rem 1rem 1rem; +} + +.api-overview-card-title { + margin: 0 0 0.5rem; + font-size: 1rem; +} + +.api-method-chips { + display: flex; + flex-wrap: wrap; + gap: 0.35rem; +} + +.api-method-chip { + border: 1px solid #dee2e6; + border-radius: 4px; + padding: 0.1rem 0.4rem; + font-size: 0.8rem; + text-decoration: none; + transition: background-color 0.2s; +} + +.api-method-chip:hover { + background-color: #f1f3f5; +} + +/* The rendered chip is Method; + cancel the global inline-code background/padding so the chip border is the + only visible box. */ +.api-method-chip code { + background: none; + padding: 0; + font-size: inherit; +} + +/* API overview grid END */ diff --git a/data/component_apis.yaml b/data/component_apis.yaml new file mode 100644 index 0000000000..4ebf973e9c --- /dev/null +++ b/data/component_apis.yaml @@ -0,0 +1,59 @@ +# Drives /reference/apis/components/overview/ via the `api-overview` shortcode. +# The `table` paths point at method-table includes auto-generated by +# .github/workflows/update_sdk_methods.py (movement-sensor is the exception: its +# table is maintained manually). If that script renames or removes a -table.md +# file, update the matching `table` path here or the Hugo build will fail. +- title: "Arm" + link: "/reference/apis/components/arm/" + table: "/static/include/components/apis/generated/arm-table.md" +- title: "Audio in" + link: "/reference/apis/components/audio-in/" + table: "/static/include/components/apis/generated/audio_in-table.md" +- title: "Audio out" + link: "/reference/apis/components/audio-out/" + table: "/static/include/components/apis/generated/audio_out-table.md" +- title: "Base" + link: "/reference/apis/components/base/" + table: "/static/include/components/apis/generated/base-table.md" +- title: "Board" + link: "/reference/apis/components/board/" + table: "/static/include/components/apis/generated/board-table.md" +- title: "Button" + link: "/reference/apis/components/button/" + table: "/static/include/components/apis/generated/button-table.md" +- title: "Camera" + link: "/reference/apis/components/camera/" + table: "/static/include/components/apis/generated/camera-table.md" +- title: "Encoder" + link: "/reference/apis/components/encoder/" + table: "/static/include/components/apis/generated/encoder-table.md" +- title: "Gantry" + link: "/reference/apis/components/gantry/" + table: "/static/include/components/apis/generated/gantry-table.md" +- title: "Generic" + link: "/reference/apis/components/generic/" + table: "/static/include/components/apis/generated/generic_component-table.md" +- title: "Gripper" + link: "/reference/apis/components/gripper/" + table: "/static/include/components/apis/generated/gripper-table.md" +- title: "Input controller" + link: "/reference/apis/components/input-controller/" + table: "/static/include/components/apis/generated/input_controller-table.md" +- title: "Motor" + link: "/reference/apis/components/motor/" + table: "/static/include/components/apis/generated/motor-table.md" +- title: "Movement sensor" + link: "/reference/apis/components/movement-sensor/" + table: "/static/include/components/apis/movement-sensor.md" +- title: "Power sensor" + link: "/reference/apis/components/power-sensor/" + table: "/static/include/components/apis/generated/power_sensor-table.md" +- title: "Sensor" + link: "/reference/apis/components/sensor/" + table: "/static/include/components/apis/generated/sensor-table.md" +- title: "Servo" + link: "/reference/apis/components/servo/" + table: "/static/include/components/apis/generated/servo-table.md" +- title: "Switch" + link: "/reference/apis/components/switch/" + table: "/static/include/components/apis/generated/switch-table.md" diff --git a/data/service_apis.yaml b/data/service_apis.yaml new file mode 100644 index 0000000000..9dd9badd27 --- /dev/null +++ b/data/service_apis.yaml @@ -0,0 +1,31 @@ +# Drives /reference/apis/services/overview/ via the `api-overview` shortcode. +# The `table` paths point at method-table includes auto-generated by +# .github/workflows/update_sdk_methods.py. If that script renames or removes a +# -table.md file, update the matching `table` path here or the Hugo build will fail. +- title: "Data management" + link: "/reference/apis/services/data/" + table: "/static/include/services/apis/generated/data_manager-table.md" +- title: "Vision" + link: "/reference/apis/services/vision/" + table: "/static/include/services/apis/generated/vision-table.md" +- title: "ML model" + link: "/reference/apis/services/ml/" + table: "/static/include/services/apis/generated/mlmodel-table.md" +- title: "Motion" + link: "/reference/apis/services/motion/" + table: "/static/include/services/apis/generated/motion-table.md" +- title: "Navigation" + link: "/reference/apis/services/navigation/" + table: "/static/include/services/apis/generated/navigation-table.md" +- title: "Generic" + link: "/reference/apis/services/generic/" + table: "/static/include/services/apis/generated/generic_service-table.md" +- title: "Base remote control" + link: "/reference/apis/services/base-rc/" + table: "/static/include/services/apis/generated/base_remote_control-table.md" +- title: "Discovery" + link: "/reference/apis/services/discovery/" + table: "/static/include/services/apis/generated/discovery-table.md" +- title: "World state store" + link: "/reference/apis/services/world-state-store/" + table: "/static/include/services/apis/generated/world_state_store-table.md" diff --git a/docs/reference/apis/_index.md b/docs/reference/apis/_index.md index 4fba9023c1..8610f7f82e 100644 --- a/docs/reference/apis/_index.md +++ b/docs/reference/apis/_index.md @@ -65,6 +65,14 @@ Manage sessions, heartbeats, and safety timeouts for connected clients. These APIs provide interfaces for controlling and getting information from the {{< glossary_tooltip term_id="component" text="components" >}} of a machine: +{{< cards >}} +{{% manualcard link="/reference/apis/components/overview/" title="Component APIs overview" %}} + +See every component API and its methods at a glance in one compact grid. + +{{% /manualcard %}} +{{< /cards >}} + {{< cards >}} {{< card link="/reference/apis/components/arm/" customTitle="Arm API" noimage="True" >}} {{< card link="/reference/apis/components/audio-in/" customTitle="Audio in API" noimage="True" >}} @@ -90,6 +98,14 @@ These APIs provide interfaces for controlling and getting information from the { These APIs provide interfaces for controlling and getting information from the services you configured on a machine. +{{< cards >}} +{{% manualcard link="/reference/apis/services/overview/" title="Service APIs overview" %}} + +See every service API and its methods at a glance in one compact grid. + +{{% /manualcard %}} +{{< /cards >}} + {{< cards >}} {{% card link="/reference/apis/services/data/" customTitle="Data management service API" noimage="True" %}} {{% card link="/reference/apis/services/vision/" customTitle="Vision service API" noimage="True" %}} diff --git a/docs/reference/apis/components/overview.md b/docs/reference/apis/components/overview.md new file mode 100644 index 0000000000..d07d4c0086 --- /dev/null +++ b/docs/reference/apis/components/overview.md @@ -0,0 +1,12 @@ +--- +title: "Component APIs overview" +linkTitle: "Overview" +weight: 1 +type: "docs" +description: "Scan every Viam component API and its methods at a glance, with links to each method's reference." +--- + +The following grid lists every {{< glossary_tooltip term_id="component" text="component" >}} API and its methods. +Select an API name to open its full reference, or select a method to jump straight to that method. + +{{< api-overview "component_apis" >}} diff --git a/docs/reference/apis/services/overview.md b/docs/reference/apis/services/overview.md new file mode 100644 index 0000000000..c7a7418969 --- /dev/null +++ b/docs/reference/apis/services/overview.md @@ -0,0 +1,12 @@ +--- +title: "Service APIs overview" +linkTitle: "Overview" +weight: 1 +type: "docs" +description: "Scan every Viam service API and its methods at a glance, with links to each method's reference." +--- + +The following grid lists every {{< glossary_tooltip term_id="service" text="service" >}} API and its methods. +Select an API name to open its full reference, or select a method to jump straight to that method. + +{{< api-overview "service_apis" >}} diff --git a/layouts/shortcodes/api-overview.html b/layouts/shortcodes/api-overview.html new file mode 100644 index 0000000000..7519962057 --- /dev/null +++ b/layouts/shortcodes/api-overview.html @@ -0,0 +1,37 @@ +{{- /* + api-overview: renders a compact CSS-grid overview of every API in a data file + and its methods. One positional arg: the data-file key (component_apis or + service_apis, from data/.yaml). + + Method lists are read at build time from the per-API method-table includes + (the same -table.md files the detail pages render), so the grid never goes + stale. Each table row's first cell is a `[`Method`](url#anchor)` link; we keep + only data rows (those starting with "| ["), take that first cell, and pull the + method name + URL from it. +*/ -}} +{{- $entries := index site.Data (.Get 0) -}} +{{- if not $entries -}} + {{- errorf "api-overview: no data file found for key %q" (.Get 0) -}} +{{- end -}} +
+ {{- range $entries -}} + {{- if not (fileExists .table) -}} + {{- errorf "api-overview: table file %q not found for %q" .table .title -}} + {{- end -}} + {{- $raw := os.ReadFile .table -}} +
+

{{ .title }}

+
+ {{- range (split $raw "\n") -}} + {{- /* keep only data rows: "| [`Method`](url) | ... |" */ -}} + {{- if hasPrefix . "| [" -}} + {{- $cell := index (split . "|") 1 -}} + {{- range findRESubmatch `\[\x60([^\x60]+)\x60\]\(([^)]+)\)` $cell -}} + {{ index . 1 }} + {{- end -}} + {{- end -}} + {{- end -}} +
+
+ {{- end -}} +
From f6000e8200396fc40df5affb431d911a21cb41e6 Mon Sep 17 00:00:00 2001 From: Brandon Shrewsbury Date: Fri, 22 May 2026 11:13:15 -0600 Subject: [PATCH 2/3] Refine API overview cards: alphabetical order, one method per line Address review feedback on the overview pages: - Sort APIs and their methods alphabetically (in the shortcode, so it holds regardless of data-file order). - List one method per line instead of wrapped chips. - Give each card a header band with the API name in Space Grotesk and a light-blue hover highlight on method rows; match the card border to the rest of the docs. Co-Authored-By: Claude Opus 4.7 (1M context) --- assets/scss/_styles_project.scss | 67 +++++++++++++++++++--------- layouts/shortcodes/api-overview.html | 36 ++++++++------- 2 files changed, 67 insertions(+), 36 deletions(-) diff --git a/assets/scss/_styles_project.scss b/assets/scss/_styles_project.scss index 9901302dca..6bf93d1bba 100644 --- a/assets/scss/_styles_project.scss +++ b/assets/scss/_styles_project.scss @@ -4095,45 +4095,70 @@ footer { .api-overview-grid { display: grid; - grid-template-columns: repeat(auto-fill, minmax(280px, 1fr)); - gap: 1rem; + grid-template-columns: repeat(auto-fill, minmax(250px, 1fr)); + gap: 1.25rem; margin: 1.5rem 0 2rem; + /* default align-items: stretch — every card in a row shares the row height */ } .api-overview-card { + display: flex; + flex-direction: column; + background: #fff; border: 1px solid #dee2e6; border-radius: 4px; - padding: 0.75rem 1rem 1rem; + overflow: hidden; +} + +.api-overview-card-header { + padding: 0.7rem 1rem; + background: #f8f9fa; + border-bottom: 1px solid #eceef0; } .api-overview-card-title { - margin: 0 0 0.5rem; - font-size: 1rem; + margin: 0; + font-family: "Space Grotesk", sans-serif; + font-size: 1.05rem; + font-weight: 600; } -.api-method-chips { - display: flex; - flex-wrap: wrap; - gap: 0.35rem; +.api-overview-card-title a { + color: #1b1b1f; + text-decoration: none; } -.api-method-chip { - border: 1px solid #dee2e6; - border-radius: 4px; - padding: 0.1rem 0.4rem; - font-size: 0.8rem; +.api-overview-card-title a:hover { + color: #3176d9; +} + +.api-method-list { + list-style: none; + margin: 0; + padding: 0.4rem; +} + +.api-method-list li { + margin: 0; +} + +.api-method-list li a { + display: block; + padding: 0.16rem 0.5rem; + border-radius: 3px; + font-size: 0.82rem; + line-height: 1.6; text-decoration: none; - transition: background-color 0.2s; + transition: background-color 0.15s ease; } -.api-method-chip:hover { - background-color: #f1f3f5; +.api-method-list li a:hover { + background-color: #eef2fb; } -/* The rendered chip is Method; - cancel the global inline-code background/padding so the chip border is the - only visible box. */ -.api-method-chip code { +/* The rendered method is Method; cancel the global + inline-code background/padding so it reads as a plain monospace link. */ +.api-method-list code { background: none; padding: 0; font-size: inherit; diff --git a/layouts/shortcodes/api-overview.html b/layouts/shortcodes/api-overview.html index 7519962057..2d33078cf6 100644 --- a/layouts/shortcodes/api-overview.html +++ b/layouts/shortcodes/api-overview.html @@ -1,37 +1,43 @@ {{- /* - api-overview: renders a compact CSS-grid overview of every API in a data file - and its methods. One positional arg: the data-file key (component_apis or + api-overview: renders a compact overview of every API in a data file and its + methods. One positional arg: the data-file key (component_apis or service_apis, from data/.yaml). Method lists are read at build time from the per-API method-table includes (the same -table.md files the detail pages render), so the grid never goes stale. Each table row's first cell is a `[`Method`](url#anchor)` link; we keep only data rows (those starting with "| ["), take that first cell, and pull the - method name + URL from it. + method name + URL from it. APIs and methods are both listed alphabetically. */ -}} {{- $entries := index site.Data (.Get 0) -}} {{- if not $entries -}} {{- errorf "api-overview: no data file found for key %q" (.Get 0) -}} {{- end -}}
- {{- range $entries -}} + {{- range (sort $entries "title") -}} {{- if not (fileExists .table) -}} {{- errorf "api-overview: table file %q not found for %q" .table .title -}} {{- end -}} {{- $raw := os.ReadFile .table -}} -
-

{{ .title }}

-
- {{- range (split $raw "\n") -}} - {{- /* keep only data rows: "| [`Method`](url) | ... |" */ -}} - {{- if hasPrefix . "| [" -}} - {{- $cell := index (split . "|") 1 -}} - {{- range findRESubmatch `\[\x60([^\x60]+)\x60\]\(([^)]+)\)` $cell -}} - {{ index . 1 }} - {{- end -}} - {{- end -}} + {{- $methods := slice -}} + {{- range (split $raw "\n") -}} + {{- /* keep only data rows: "| [`Method`](url) | ... |" */ -}} + {{- if hasPrefix . "| [" -}} + {{- $cell := index (split . "|") 1 -}} + {{- range findRESubmatch `\[\x60([^\x60]+)\x60\]\(([^)]+)\)` $cell -}} + {{- $methods = $methods | append (dict "name" (index . 1) "url" (index . 2)) -}} {{- end -}} + {{- end -}} + {{- end -}} +
+
+

{{ .title }}

+
    + {{- range (sort $methods "name") -}} +
  • {{ .name }}
    • + {{- end -}} +
{{- end -}}
From 2c7123c2bda4f432fb6875a6d45a2c5a3aba5a68 Mon Sep 17 00:00:00 2001 From: Brandon Shrewsbury Date: Fri, 22 May 2026 11:30:11 -0600 Subject: [PATCH 3/3] Drop Navigation from the service API overview Merge latest main, which removed the Navigation service API (#5067). Its generated method table no longer exists, so remove the Navigation entry from data/service_apis.yaml; the overview now lists 8 services. Co-Authored-By: Claude Opus 4.7 (1M context) --- data/service_apis.yaml | 3 --- 1 file changed, 3 deletions(-) diff --git a/data/service_apis.yaml b/data/service_apis.yaml index 9dd9badd27..d1dec2866e 100644 --- a/data/service_apis.yaml +++ b/data/service_apis.yaml @@ -14,9 +14,6 @@ - title: "Motion" link: "/reference/apis/services/motion/" table: "/static/include/services/apis/generated/motion-table.md" -- title: "Navigation" - link: "/reference/apis/services/navigation/" - table: "/static/include/services/apis/generated/navigation-table.md" - title: "Generic" link: "/reference/apis/services/generic/" table: "/static/include/services/apis/generated/generic_service-table.md"