diff --git a/assets/scss/_styles_project.scss b/assets/scss/_styles_project.scss index b06a7ad257..6bf93d1bba 100644 --- a/assets/scss/_styles_project.scss +++ b/assets/scss/_styles_project.scss @@ -4090,3 +4090,78 @@ footer { } /* Feedback System Styles END */ + +/* API overview grid START */ + +.api-overview-grid { + display: grid; + 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; + overflow: hidden; +} + +.api-overview-card-header { + padding: 0.7rem 1rem; + background: #f8f9fa; + border-bottom: 1px solid #eceef0; +} + +.api-overview-card-title { + margin: 0; + font-family: "Space Grotesk", sans-serif; + font-size: 1.05rem; + font-weight: 600; +} + +.api-overview-card-title a { + color: #1b1b1f; + text-decoration: none; +} + +.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.15s ease; +} + +.api-method-list li a:hover { + background-color: #eef2fb; +} + +/* 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; +} + +/* 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..d1dec2866e --- /dev/null +++ b/data/service_apis.yaml @@ -0,0 +1,28 @@ +# 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: "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..2d33078cf6 --- /dev/null +++ b/layouts/shortcodes/api-overview.html @@ -0,0 +1,43 @@ +{{- /* + 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. 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 (sort $entries "title") -}} + {{- if not (fileExists .table) -}} + {{- errorf "api-overview: table file %q not found for %q" .table .title -}} + {{- end -}} + {{- $raw := os.ReadFile .table -}} + {{- $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 -}} +