Document registry deprecation and machine summary methods on the fleet page - #5187
Document registry deprecation and machine summary methods on the fleet page#5187btshrewsbury-viam wants to merge 5 commits into
Conversation
The Python, TypeScript, and Flutter SDKs expose a resource-level GetStatus method (backed by the common GetStatus RPC) on every component and most services, but it had no rows in sdk_protos_map.csv, so the API reference never mentioned it and the weekly SDK method coverage job flagged ~70 unused-method warnings. Add a GetStatus row for each of the 18 components and 8 services, filling only the SDK columns the coverage scraper actually finds (the Go SDK has no per-resource GetStatus; Flutter lacks encoder, input controller, and switch). Add a proto description override file per resource, and regenerate the affected component and service markdown. Also ignore the capitalized 'GetStatus' the Python scraper picks up from the world_state_store page, matching the existing entries for that page's other proto-cased duplicates (ListUUIDs, GetTransform). Refs #5142.
The first-sentence extractor for method-table descriptions only
stripped percent-style ({{% alert %}}) shortcode blocks. The
motion.MoveOnMap.md override starts with an angle-bracket
({{< alert >}}) block, so regenerating leaked an unclosed shortcode
opener into motion-table.md and broke the Hugo build. Strip
angle-bracket blocks the same way, non-greedily so a description
between two blocks survives.
…ence/apis The docs restructure moved the API reference pages from /dev/reference/apis/* to /reference/apis/*, leaving /dev/reference as meta-refresh alias stubs. The generator still hardcoded the old prefix, so the previous regeneration pointed every method-table link at a stub page and htmltest failed. Update the anchor prefixes and regenerate the files in this PR's scope.
…pload methods Documents seven released fleet/data methods flagged by the SDK method coverage job: - DeprecateRegistryItem / UndeprecateRegistryItem and their Version variants (Python + TypeScript), joining the already-documented registry item CRUD methods. - ListMachineSummaries (Go): fleet-wide machine summary listing. - GetRobotPartByNameAndLocation (Go): fills the missing Go method on the already-documented proto row. - UploadImageToDatasets (Go) on the data manager service, alongside the existing UploadBinaryDataToDatasets. Adds CSV rows/columns, proto description overrides (rewording the two pre-staged override files to imperative table style), and regenerates the fleet and data manager markdown. Refs #5142.
|
Merge order: merge #5184 first. This PR is stacked on the Issue linkage: refs #5142 but does not close it. The Go DataClient methods deliberately excluded here (sequences CRUD, app-side Generated by Claude Code |
Split the data manager service method out so the fleet-page changes and the data manager change can be reviewed independently; they share no generated files.
btshrewsbury-viam
changed the title
|
Scope change: the Generated by Claude Code |
|
Marvin (@enternal-L) Could you please review this PR? It's mostly generated stuff, but there are two .md files that could use a double check |
|
Hey btshrewsbury-viam — this PR has been approved and CI has been green for 3+ business days. Ready to merge? Auto-comment from overwatch. Will not re-nudge for 7 days. |
Shannon Bradshaw (shannonbradshaw)
left a comment
Shannon Bradshaw (shannonbradshaw)
left a comment
There was a problem hiding this comment.
I independently verified this PR's claims against source (api a05c12b5, rdk cf13e7a16, app 844583faf, viam-python-sdk 6a6e035ba, viam-typescript-sdk ca10ef2c9, all at current main). Most of it checks out cleanly:
- All four registry deprecation RPCs exist in the proto (
app.proto:290–306), and the Python and TypeScript tabs match the SDK source verbatim — signatures, parameter descriptions, and examples all trace toapp_client.py:2400–2461andapp-client.ts:1660–1721. GetRobotPartByNameAndLocationis done right: the Go tab sits inside the existing section, the argument order matchesapp/app_client.go:2991, and the CSV row was edited in place.- The
ListMachineSummariesGo signature and[]*LocationSummaryreturn type matchapp/app_client.go:2910. The example'slimitof0is behaviorally safe — the app backend treats any limit ≤ 0 as "no limit" (domains/fleetdashboard/server.go:98–102). (Side note: the proto comment says unset defaults to 100; the handler says otherwise — an api-repo comment bug worth an upstream note, though the docs don't repeat the claim.)
Four findings, first one worth fixing before merge:
1. ListMachineSummaries is now documented twice on the page. The PR adds a new Go-only CSV row (line 411, after ListRobots) while the pre-existing TypeScript-only row remains (line 421, after ListMachineFragments). The generator emits one section per row, so the head file has two ### ListMachineSummaries headings (app.md lines 3382 and 4090) and two identical rows in app-table.md (lines 49 and 59), both linking to #listmachinesummaries. Rendered, the second heading gets anchor #listmachinesummaries-1 that nothing links to, and the Go and TypeScript tabs are split across two sections instead of sharing one tabset. Fix: merge into a single CSV row (app,ListMachineSummaries,,,ListMachineSummaries,,listMachineSummaries) at one position and regenerate.
2. The Go example for ListMachineSummaries is wrong. It passes []string{locationID} in the fragmentIDs position and []string{fragmetnID} (note the typo) in the locationIDs position — verified against the signature order (ctx, organizationID, fragmentIDs, locationIDs, limit). The example is scraped verbatim from the rdk doc comment introduced in rdk#5608 (app/app_client.go:2896–2905), which also has the ragged indentation. The durable fix is correcting the rdk doc comment and regenerating.
3. Missing parameter types in the new Go tabs (minor scraper artifact): fragmentIDs and name render with no type or description — both are the first identifier in a combined Go declaration (fragmentIDs, locationIDs []string; name, locationID string), which the Go scraper mishandles.
4. Regeneration churn regression (informational, upstream): create_role/remove_role/change_role now render private type aliases _ROLE_TYPE / _RESOURCE_TYPE_TYPE where the readable Literal['owner'] | Literal['operator'] used to appear. The prose descriptions still name the allowed values, so not blocking, but it's a readability regression from the SDK/generator side.
|
Hey btshrewsbury-viam — this PR has been approved and CI has been green for 9+ business days. Ready to merge? Auto-comment from overwatch. Will not re-nudge for 7 days. |
|
Hey btshrewsbury-viam — this PR has been approved and CI has been green for 14+ business days. Ready to merge? Auto-comment from overwatch. Will not re-nudge for 7 days. |
3 participants
What this adds
Six released fleet methods flagged by the weekly SDK method coverage job (#5142), all on the Fleet Management API page:
The
UploadImageToDatasetsdata manager change originally in this PR moved to #5193 so the two can be reviewed independently — they share no generated files.Deliberately not included
The Go DataClient methods the coverage job also flags (sequences CRUD, the app-side
UploadImageToDatasets) cannot currently be documented on the data client page — the Go scraper attributes everygo.viam.com/rdk/apppackage method to the fleet page, and the data client page has no Go tabs. Tracked in #5190 rather than misplaced here.Merge order
Stacked on #5184 (shared regeneration baseline). Merge #5184 first; GitHub retargets this automatically. Refs #5142 but does not close it (remaining warnings tracked in #5188/#5189/#5190).
Verification
Targeted coverage runs: all six warnings cleared, no missing-override warnings, links verified against the current /reference/apis/ paths.
Refs #5142